mirror of
https://github.com/Azgaar/Fantasy-Map-Generator.git
synced 2025-12-16 17:31:24 +01:00
Merge pull request #3 from LeieSistal/claude/wiki-documentation-011CUoYyiWtfJYz6L1LGuHey
Add comprehensive wiki documentation
This commit is contained in:
Leie Sistal
GitHub
commit
fd44e076ae
8 changed files with 4716 additions and 0 deletions
461
wiki/Architecture.md
Normal file
461
wiki/Architecture.md
Normal file
|
|
@ -0,0 +1,461 @@
|
|||
# System Architecture
|
||||
|
||||
This document describes the high-level architecture of the Fantasy Map Generator, including its design patterns, component organization, and key technical decisions.
|
||||
|
||||
## Overview
|
||||
|
||||
The Fantasy Map Generator is a client-side web application built with vanilla JavaScript. It uses a modular architecture where each major feature is encapsulated in its own module, communicating through shared global state objects.
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ index.html │
|
||||
│ (Main Entry Point) │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ main.js │ │ versioning.js│ │ index.css │
|
||||
│ (Core Logic) │ │(Version Mgmt)│ │ (Styles) │
|
||||
└──────┬───────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
│ Loads & Coordinates
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ modules/ │
|
||||
│ ┌────────────────┬────────────────┬─────────────────┐ │
|
||||
│ │ Generators │ Renderers │ UI │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • heightmap │ • coa-renderer │ • editors/ (41) │ │
|
||||
│ │ • rivers │ • relief-icons │ • dialogs │ │
|
||||
│ │ • cultures │ • ocean-layers │ • tools │ │
|
||||
│ │ • burgs/states │ │ │ │
|
||||
│ │ • religions │ │ │ │
|
||||
│ │ • routes │ │ │ │
|
||||
│ │ • military │ │ │ │
|
||||
│ │ • markers │ │ │ │
|
||||
│ │ • names │ │ │ │
|
||||
│ │ • coa │ │ │ │
|
||||
│ │ • biomes │ │ │ │
|
||||
│ └────────────────┴────────────────┴─────────────────┘ │
|
||||
│ ┌────────────────┬────────────────┐ │
|
||||
│ │ I/O │ Dynamic │ │
|
||||
│ │ • save/load │ • editors │ │
|
||||
│ │ • export │ • utilities │ │
|
||||
│ └────────────────┴────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Uses
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ libs/ │
|
||||
│ • d3.min.js (Data visualization & SVG) │
|
||||
│ • delaunator.min.js (Delaunay triangulation) │
|
||||
│ • jquery.min.js (DOM manipulation) │
|
||||
│ • jquery-ui.min.js (UI widgets) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Manipulates
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Global State │
|
||||
│ • grid (Voronoi diagram + terrain data) │
|
||||
│ • pack (Civilizations + derived data) │
|
||||
│ • seed (Random seed) │
|
||||
│ • options (Generation parameters) │
|
||||
│ • notes (User annotations) │
|
||||
│ • mapHistory (Undo/redo state) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Renders to
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ SVG Canvas │
|
||||
│ 30+ layered groups for different map elements │
|
||||
│ (oceans, terrain, rivers, borders, labels, etc.) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Entry Point (index.html + main.js)
|
||||
|
||||
**index.html** serves as the application shell, containing:
|
||||
- SVG canvas with ~30 layered groups (see SVG Layer Structure below)
|
||||
- UI controls and dialogs
|
||||
- Script includes for libraries and modules
|
||||
|
||||
**main.js** (67KB+) is the application core, containing:
|
||||
- Initialization and bootstrapping logic
|
||||
- Main generation workflow (`generate()` function)
|
||||
- Global state management
|
||||
- Event handlers and UI coordination
|
||||
- Utility functions used throughout the app
|
||||
|
||||
### 2. Module Organization
|
||||
|
||||
All modules follow the **Revealing Module Pattern**:
|
||||
|
||||
```javascript
|
||||
window.ModuleName = (function() {
|
||||
// Private variables and functions
|
||||
const privateData = {};
|
||||
|
||||
function privateFunction() {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
// Public API
|
||||
function publicFunction() {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
return {
|
||||
publicFunction
|
||||
};
|
||||
})();
|
||||
```
|
||||
|
||||
This provides:
|
||||
- **Encapsulation** - Private implementation details
|
||||
- **Namespace management** - Clean global scope
|
||||
- **Explicit interfaces** - Clear public APIs
|
||||
|
||||
### 3. Module Categories
|
||||
|
||||
#### Generators (`modules/`)
|
||||
|
||||
These modules create map data procedurally:
|
||||
|
||||
- **heightmap-generator.js** - Terrain elevation using templates or images
|
||||
- **river-generator.js** - Water flow simulation and river networks
|
||||
- **cultures-generator.js** - Culture placement and expansion
|
||||
- **burgs-and-states.js** - Capitals, towns, and political boundaries
|
||||
- **religions-generator.js** - Religion creation and spread
|
||||
- **routes-generator.js** - Road and trade route networks
|
||||
- **military-generator.js** - Military units and regiments
|
||||
- **markers-generator.js** - Map markers and POIs
|
||||
- **names-generator.js** - Procedural name generation using Markov chains
|
||||
- **coa-generator.js** - Coat of arms generation
|
||||
- **biomes.js** - Biome assignment based on climate
|
||||
- **lakes.js** - Lake creation and management
|
||||
|
||||
#### Renderers (`modules/renderers/`)
|
||||
|
||||
These modules handle visualization:
|
||||
|
||||
- **coa-renderer.js** - Renders coats of arms to SVG
|
||||
- **relief-icons.js** - Terrain icon rendering
|
||||
- **ocean-layers.js** - Ocean visualization
|
||||
|
||||
#### UI Modules (`modules/ui/`)
|
||||
|
||||
41+ specialized editors, including:
|
||||
- Heightmap editor, coastline editor, rivers editor
|
||||
- Biomes editor, relief editor, temperature/precipitation graphs
|
||||
- Burg editor, states editor, cultures editor, religions editor
|
||||
- Provinces editor, routes editor, military overview
|
||||
- Markers editor, notes editor, zones editor
|
||||
- Style editors, options editor, tools
|
||||
|
||||
Each editor is a separate file that creates a dialog interface for editing specific map aspects.
|
||||
|
||||
#### I/O Modules (`modules/io/`)
|
||||
|
||||
Handle data persistence and export:
|
||||
- Save/load functionality (.map format)
|
||||
- Export to various formats (JSON, SVG, PNG, etc.)
|
||||
- Cloud storage integration
|
||||
|
||||
#### Dynamic Modules (`modules/dynamic/`)
|
||||
|
||||
Runtime utilities and helpers loaded dynamically as needed.
|
||||
|
||||
### 4. SVG Layer Structure
|
||||
|
||||
The map is rendered to an SVG canvas with ~30 named groups, organized by z-index:
|
||||
|
||||
```xml
|
||||
<svg id="map">
|
||||
<!-- Background -->
|
||||
<g id="oceanLayers"></g>
|
||||
<g id="oceanPattern"></g>
|
||||
|
||||
<!-- Terrain -->
|
||||
<g id="landmass"></g>
|
||||
<g id="texture"></g>
|
||||
<g id="terrs"></g>
|
||||
<g id="biomes"></g>
|
||||
|
||||
<!-- Water Features -->
|
||||
<g id="ice"></g>
|
||||
<g id="lakes"></g>
|
||||
<g id="coastline"></g>
|
||||
<g id="rivers"></g>
|
||||
|
||||
<!-- Political Boundaries -->
|
||||
<g id="regions"></g>
|
||||
<g id="statesBody"></g>
|
||||
<g id="statesHalo"></g>
|
||||
<g id="provs"></g>
|
||||
<g id="borders"></g>
|
||||
|
||||
<!-- Population & Infrastructure -->
|
||||
<g id="zones"></g>
|
||||
<g id="population"></g>
|
||||
<g id="routes"></g>
|
||||
<g id="roads"></g>
|
||||
<g id="trails"></g>
|
||||
<g id="searoutes"></g>
|
||||
|
||||
<!-- Settlements & Icons -->
|
||||
<g id="temp"></g>
|
||||
<g id="military"></g>
|
||||
<g id="icons"></g>
|
||||
<g id="burgIcons"></g>
|
||||
<g id="burgLabels"></g>
|
||||
|
||||
<!-- Information Layers -->
|
||||
<g id="labels"></g>
|
||||
<g id="markers"></g>
|
||||
<g id="prec"></g>
|
||||
<g id="temperature"></g>
|
||||
<g id="ruler"></g>
|
||||
<g id="grid"></g>
|
||||
<g id="coordinates"></g>
|
||||
<g id="compass"></g>
|
||||
<g id="legend"></g>
|
||||
|
||||
<!-- Overlays -->
|
||||
<g id="debug"></g>
|
||||
<g id="overlay"></g>
|
||||
</svg>
|
||||
```
|
||||
|
||||
Each layer can be toggled on/off independently. Elements are drawn to specific layers based on their type, allowing for proper z-ordering and selective rendering.
|
||||
|
||||
## Design Patterns
|
||||
|
||||
### 1. Global State Pattern
|
||||
|
||||
The application uses several global objects to store state:
|
||||
|
||||
```javascript
|
||||
// Main data structures
|
||||
let grid = {}; // Voronoi diagram + terrain
|
||||
let pack = {}; // Civilizations + derived data
|
||||
let seed = ""; // Random seed for reproducibility
|
||||
let options = {}; // Generation parameters
|
||||
|
||||
// Additional state
|
||||
let notes = []; // User annotations
|
||||
let mapHistory = []; // Undo/redo states
|
||||
let customization = 0; // Customization level
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Simple communication between modules
|
||||
- Easy serialization for save/load
|
||||
- No complex state management library needed
|
||||
|
||||
**Drawbacks:**
|
||||
- Global namespace pollution
|
||||
- Implicit dependencies between modules
|
||||
- Harder to reason about data flow
|
||||
|
||||
### 2. Typed Arrays for Performance
|
||||
|
||||
To handle large datasets efficiently, the application uses JavaScript Typed Arrays:
|
||||
|
||||
```javascript
|
||||
pack.cells = {
|
||||
i: new Uint32Array(cells), // Cell indices
|
||||
h: new Uint8Array(cells), // Height (0-255)
|
||||
s: new Uint16Array(cells), // State ID
|
||||
culture: new Uint16Array(cells), // Culture ID
|
||||
// ... etc
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- 50-90% memory reduction vs regular arrays
|
||||
- Faster iteration and access
|
||||
- Enforced data types prevent bugs
|
||||
|
||||
### 3. Seeded Random Generation
|
||||
|
||||
Uses **aleaPRNG** for reproducible randomness:
|
||||
|
||||
```javascript
|
||||
Math.random = aleaPRNG(seed);
|
||||
```
|
||||
|
||||
Any map can be regenerated identically using the same seed, enabling:
|
||||
- Sharing maps by seed string
|
||||
- Debugging reproducibility
|
||||
- Procedural generation consistency
|
||||
|
||||
### 4. Event-Driven UI Updates
|
||||
|
||||
UI editors trigger updates through event listeners:
|
||||
|
||||
```javascript
|
||||
$('#someInput').on('change', function() {
|
||||
updateMapElement();
|
||||
drawLayers();
|
||||
});
|
||||
```
|
||||
|
||||
Changes immediately reflect on the map, providing real-time feedback.
|
||||
|
||||
### 5. D3.js Data Binding
|
||||
|
||||
Uses D3.js for declarative data-to-DOM binding:
|
||||
|
||||
```javascript
|
||||
const cells = d3.select('#biomes').selectAll('polygon')
|
||||
.data(pack.cells.i.filter(i => pack.cells.h[i] >= 20))
|
||||
.enter().append('polygon')
|
||||
.attr('points', d => getCellPolygonPoints(d))
|
||||
.attr('fill', d => biomesData.color[pack.cells.biome[d]]);
|
||||
```
|
||||
|
||||
This pattern allows efficient updates when data changes.
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Generation Pipeline
|
||||
|
||||
```
|
||||
User Input (seed, options)
|
||||
↓
|
||||
Generate Grid (Voronoi)
|
||||
↓
|
||||
Heightmap Generation
|
||||
↓
|
||||
Feature Detection (land/water)
|
||||
↓
|
||||
Climate Calculation (temp/prec)
|
||||
↓
|
||||
Repack Grid → Pack
|
||||
↓
|
||||
Rivers & Lakes
|
||||
↓
|
||||
Biome Assignment
|
||||
↓
|
||||
Culture Generation
|
||||
↓
|
||||
State Generation
|
||||
↓
|
||||
Settlement Generation
|
||||
↓
|
||||
Route Generation
|
||||
↓
|
||||
Rendering to SVG
|
||||
↓
|
||||
User Interaction (editing)
|
||||
```
|
||||
|
||||
### Edit-Render Cycle
|
||||
|
||||
```
|
||||
User Edits Data
|
||||
↓
|
||||
Update Global State (grid/pack)
|
||||
↓
|
||||
Trigger Render Function
|
||||
↓
|
||||
D3.js Updates SVG Elements
|
||||
↓
|
||||
Browser Renders Changes
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Cell Count
|
||||
|
||||
Default: **~10,000 cells** in the grid
|
||||
- More cells = higher detail + slower generation
|
||||
- Fewer cells = lower detail + faster generation
|
||||
- Configurable in options
|
||||
|
||||
### 2. Rendering Optimization
|
||||
|
||||
- **Selective Layer Drawing** - Only redraw changed layers
|
||||
- **D3 Data Binding** - Efficient DOM updates
|
||||
- **Typed Arrays** - Memory-efficient storage
|
||||
- **Debounced Updates** - Prevent excessive redraws during editing
|
||||
|
||||
### 3. Lazy Loading
|
||||
|
||||
Some modules are loaded on-demand:
|
||||
- 3D view components
|
||||
- Export utilities
|
||||
- Advanced editors
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Core Technologies
|
||||
|
||||
- **JavaScript (ES6+)** - Core language
|
||||
- **SVG** - Vector graphics rendering
|
||||
- **HTML5 Canvas** - Some bitmap operations
|
||||
- **CSS3** - Styling and layout
|
||||
|
||||
### Key Libraries
|
||||
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| **D3.js** | v7+ | Data visualization, SVG manipulation |
|
||||
| **Delaunator** | Latest | Fast Delaunay triangulation |
|
||||
| **jQuery** | 3.x | DOM manipulation, AJAX |
|
||||
| **jQuery UI** | 1.x | Dialogs, sliders, sortable |
|
||||
|
||||
### Algorithms & Techniques
|
||||
|
||||
- **Voronoi Diagrams** - Spatial partitioning for cells
|
||||
- **Delaunay Triangulation** - Dual graph for Voronoi
|
||||
- **Markov Chains** - Procedural name generation
|
||||
- **Heightmap Templates** - Terrain generation patterns
|
||||
- **Flux-based River Simulation** - Realistic water flow
|
||||
- **Expansion Algorithms** - Culture and state growth
|
||||
- **Dijkstra's Algorithm** - Route pathfinding
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
**Recommended:** Modern evergreen browsers
|
||||
- Chrome/Edge (Chromium) - Best performance
|
||||
- Firefox - Good performance
|
||||
- Safari - Good performance
|
||||
|
||||
**Required Features:**
|
||||
- ES6 JavaScript support
|
||||
- SVG 1.1
|
||||
- Canvas API
|
||||
- Local Storage API
|
||||
- File API for save/load
|
||||
|
||||
## Deployment
|
||||
|
||||
The application is:
|
||||
- **Static** - No server-side processing required
|
||||
- **Client-side** - Runs entirely in the browser
|
||||
- **Portable** - Can run from local filesystem or any web server
|
||||
- **GitHub Pages** - Official deployment at azgaar.github.io
|
||||
|
||||
## Future Architecture Considerations
|
||||
|
||||
The codebase is acknowledged to be "messy and requires re-design" (per README). Potential improvements:
|
||||
|
||||
1. **Module Bundling** - Use webpack/rollup for better dependency management
|
||||
2. **State Management** - Consider Redux/MobX for clearer data flow
|
||||
3. **TypeScript** - Type safety and better IDE support
|
||||
4. **Component Framework** - Vue/React for more maintainable UI
|
||||
5. **Web Workers** - Offload heavy generation to background threads
|
||||
6. **WASM** - Performance-critical sections in Rust/C++
|
||||
|
||||
However, the current architecture works well for its purpose and maintains accessibility for contributors familiar with vanilla JavaScript.
|
||||
630
wiki/Data-Model.md
Normal file
630
wiki/Data-Model.md
Normal file
|
|
@ -0,0 +1,630 @@
|
|||
# Data Model
|
||||
|
||||
This document describes the data structures used by the Fantasy Map Generator. Understanding these structures is essential for contributing to the project or building extensions.
|
||||
|
||||
## Overview
|
||||
|
||||
The generator maintains two primary data structures:
|
||||
|
||||
1. **`grid`** - The initial Voronoi diagram with terrain and climate data
|
||||
2. **`pack`** - A packed/filtered version with civilizations and derived features
|
||||
|
||||
Both are global objects accessible throughout the application. All map data can be serialized to/from these structures for save/load functionality.
|
||||
|
||||
## Grid Object
|
||||
|
||||
The `grid` object represents the initial Voronoi diagram created from ~10,000 jittered points. It contains the raw terrain and climate data.
|
||||
|
||||
### Structure
|
||||
|
||||
```javascript
|
||||
grid = {
|
||||
// Core Voronoi data
|
||||
points: [[x1, y1], [x2, y2], ...], // Array of [x, y] coordinates
|
||||
cells: {
|
||||
i: Uint32Array, // Cell indices [0, 1, 2, ...]
|
||||
v: Array, // Vertices indices for each cell
|
||||
c: Array, // Adjacent cell indices
|
||||
b: Uint8Array, // Border cell (1) or not (0)
|
||||
f: Uint16Array, // Feature ID (island/ocean/lake)
|
||||
t: Int8Array, // Cell type: -1=ocean, -2=lake, 1=land
|
||||
h: Uint8Array, // Height (0-100, where 20 is sea level)
|
||||
temp: Int8Array, // Temperature (-128 to 127)
|
||||
prec: Uint8Array, // Precipitation (0-255)
|
||||
area: Float32Array, // Cell area in square pixels
|
||||
},
|
||||
|
||||
// Vertices
|
||||
vertices: {
|
||||
p: [[x, y], ...], // Vertex coordinates
|
||||
v: Array, // Voronoi vertices
|
||||
c: Array // Adjacent cells to each vertex
|
||||
},
|
||||
|
||||
// Seeds (feature centers)
|
||||
seeds: {
|
||||
i: Uint16Array, // Seed cell indices
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Key Properties
|
||||
|
||||
#### cells.i (Index)
|
||||
- Unique identifier for each cell
|
||||
- Values: `0` to `n-1` where `n` is cell count
|
||||
- Used to reference cells throughout the application
|
||||
|
||||
#### cells.h (Height)
|
||||
- Elevation value for the cell
|
||||
- Range: `0-100` (typically)
|
||||
- Convention: `0-20` = water, `20+` = land
|
||||
- Higher values = higher elevation
|
||||
|
||||
#### cells.temp (Temperature)
|
||||
- Temperature in relative units
|
||||
- Range: `-128` to `127` (signed 8-bit)
|
||||
- Calculated based on latitude and other factors
|
||||
- Affects biome assignment
|
||||
|
||||
#### cells.prec (Precipitation)
|
||||
- Rainfall/moisture level
|
||||
- Range: `0-255` (unsigned 8-bit)
|
||||
- Affects river generation and biomes
|
||||
- Higher near coasts and prevailing winds
|
||||
|
||||
#### cells.f (Feature ID)
|
||||
- Identifies which landmass/ocean/lake the cell belongs to
|
||||
- Each contiguous land area gets a unique ID
|
||||
- Used for island detection and feature management
|
||||
|
||||
#### cells.t (Type)
|
||||
- Quick type classification
|
||||
- Values: `-2` = lake, `-1` = ocean, `0` = coast, `1` = land
|
||||
- Used for filtering and quick checks
|
||||
|
||||
### Grid Methods
|
||||
|
||||
The grid doesn't expose many methods directly. Most operations are performed by utility functions in `main.js`:
|
||||
|
||||
```javascript
|
||||
// Generate initial grid
|
||||
generateGrid();
|
||||
|
||||
// Get neighboring cells
|
||||
const neighbors = grid.cells.c[cellId];
|
||||
|
||||
// Check if cell is land
|
||||
const isLand = grid.cells.h[cellId] >= 20;
|
||||
```
|
||||
|
||||
## Pack Object
|
||||
|
||||
The `pack` object is derived from `grid` after initial generation. It contains only land cells and adds civilization data.
|
||||
|
||||
### Structure
|
||||
|
||||
```javascript
|
||||
pack = {
|
||||
// Cell data (filtered from grid, only land cells)
|
||||
cells: {
|
||||
i: Uint32Array, // Cell indices
|
||||
p: Array, // [x, y] coordinates
|
||||
v: Array, // Vertex indices
|
||||
c: Array, // Adjacent cells
|
||||
area: Float32Array, // Cell area
|
||||
|
||||
// Terrain data (from grid)
|
||||
h: Uint8Array, // Height
|
||||
temp: Int8Array, // Temperature
|
||||
prec: Uint8Array, // Precipitation
|
||||
|
||||
// Water features
|
||||
r: Uint16Array, // River ID (0 = no river)
|
||||
fl: Uint16Array, // Water flux (amount of water flowing)
|
||||
conf: Uint8Array, // River confluence count
|
||||
|
||||
// Biomes & terrain
|
||||
biome: Uint8Array, // Biome type ID
|
||||
|
||||
// Civilization
|
||||
s: Uint16Array, // State ID (0 = neutral)
|
||||
culture: Uint16Array, // Culture ID
|
||||
religion: Uint16Array, // Religion ID (0 = no religion)
|
||||
province: Uint16Array, // Province ID
|
||||
burg: Uint16Array, // Burg ID (0 = no settlement)
|
||||
|
||||
// Infrastructure
|
||||
road: Uint16Array, // Road power (0 = no road)
|
||||
crossroad: Uint16Array, // Crossroad value
|
||||
|
||||
// Derived properties
|
||||
pop: Float32Array, // Population density
|
||||
harbor: Uint8Array, // Harbor/port status
|
||||
},
|
||||
|
||||
// Vertices
|
||||
vertices: {
|
||||
p: Array, // [x, y] coordinates
|
||||
c: Array, // Adjacent cells
|
||||
v: Array // Voronoi data
|
||||
},
|
||||
|
||||
// Burgs (settlements)
|
||||
burgs: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
cell: Number, // Cell index where burg is located
|
||||
x: Number, // X coordinate
|
||||
y: Number, // Y coordinate
|
||||
name: String, // Settlement name
|
||||
feature: Number, // Feature (island) ID
|
||||
|
||||
// Political
|
||||
state: Number, // State ID
|
||||
capital: Boolean, // Is state capital
|
||||
|
||||
// Cultural
|
||||
culture: Number, // Culture ID
|
||||
|
||||
// Population
|
||||
population: Number, // Total population
|
||||
type: String, // Settlement type (city, town, etc.)
|
||||
|
||||
// Other
|
||||
port: Number, // Port/harbor value
|
||||
citadel: Boolean, // Has citadel/castle
|
||||
}
|
||||
],
|
||||
|
||||
// States (political entities)
|
||||
states: [
|
||||
{
|
||||
i: Number, // Unique ID (0 = neutral)
|
||||
name: String, // State name
|
||||
color: String, // CSS color code
|
||||
capital: Number, // Capital burg ID
|
||||
|
||||
// Cultural
|
||||
culture: Number, // Dominant culture ID
|
||||
religion: Number, // State religion ID
|
||||
|
||||
// Political
|
||||
type: String, // Government type (Kingdom, Empire, etc.)
|
||||
expansionism: Number, // Expansion aggressiveness (0-1)
|
||||
form: String, // "Monarchy", "Republic", etc.
|
||||
|
||||
// Geographic
|
||||
area: Number, // Total area in cells
|
||||
cells: Number, // Number of cells
|
||||
|
||||
// Population
|
||||
rural: Number, // Rural population
|
||||
urban: Number, // Urban population
|
||||
|
||||
// Military
|
||||
military: Array, // Military units
|
||||
|
||||
// Diplomacy
|
||||
diplomacy: Array, // Relations with other states
|
||||
|
||||
// Other
|
||||
pole: [x, y], // Pole of inaccessibility (label position)
|
||||
alert: Number, // Alert level
|
||||
alive: Number, // Is state alive (1) or removed (0)
|
||||
}
|
||||
],
|
||||
|
||||
// Cultures
|
||||
cultures: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
name: String, // Culture name
|
||||
base: Number, // Base name generation set
|
||||
type: String, // Culture type (Generic, River, etc.)
|
||||
|
||||
// Geographic
|
||||
center: Number, // Origin cell
|
||||
color: String, // CSS color code
|
||||
|
||||
// Area & population
|
||||
area: Number, // Total area
|
||||
cells: Number, // Number of cells
|
||||
rural: Number, // Rural population
|
||||
urban: Number, // Urban population
|
||||
|
||||
// Cultural traits
|
||||
expansionism: Number, // Expansion rate
|
||||
shield: String, // Shield shape for CoA
|
||||
code: String, // Two-letter code
|
||||
}
|
||||
],
|
||||
|
||||
// Religions
|
||||
religions: [
|
||||
{
|
||||
i: Number, // Unique ID (0 = no religion)
|
||||
name: String, // Religion name
|
||||
color: String, // CSS color code
|
||||
type: String, // Religion type (Folk, Organized, etc.)
|
||||
form: String, // Form (Cult, Church, etc.)
|
||||
|
||||
// Origins
|
||||
culture: Number, // Origin culture ID
|
||||
center: Number, // Origin cell
|
||||
|
||||
// Geographic
|
||||
area: Number, // Total area
|
||||
cells: Number, // Number of cells
|
||||
rural: Number, // Rural population
|
||||
urban: Number, // Urban population
|
||||
|
||||
// Deities & beliefs
|
||||
deity: String, // Deity name (if applicable)
|
||||
expansion: String, // Expansion strategy
|
||||
expansionism: Number, // Expansion rate
|
||||
code: String, // Two-letter code
|
||||
}
|
||||
],
|
||||
|
||||
// Rivers
|
||||
rivers: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
source: Number, // Source cell
|
||||
mouth: Number, // Mouth cell
|
||||
cells: Array, // Array of cell indices along river
|
||||
length: Number, // River length
|
||||
width: Number, // River width
|
||||
name: String, // River name
|
||||
type: String, // River type
|
||||
parent: Number, // Parent river (for tributaries)
|
||||
}
|
||||
],
|
||||
|
||||
// Features (landmasses, oceans, lakes)
|
||||
features: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
land: Boolean, // Is land (true) or water (false)
|
||||
border: Boolean, // Touches map border
|
||||
type: String, // "island", "ocean", "lake"
|
||||
cells: Number, // Number of cells
|
||||
firstCell: Number, // First cell of feature
|
||||
group: String, // Group name (for islands)
|
||||
area: Number, // Total area
|
||||
height: Number, // Average height
|
||||
}
|
||||
],
|
||||
|
||||
// Provinces
|
||||
provinces: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
state: Number, // State ID
|
||||
name: String, // Province name
|
||||
formName: String, // Form name (e.g., "Duchy of X")
|
||||
color: String, // CSS color code
|
||||
|
||||
// Capital
|
||||
burg: Number, // Capital burg ID
|
||||
center: Number, // Center cell
|
||||
|
||||
// Geography
|
||||
area: Number, // Total area
|
||||
cells: Number, // Number of cells
|
||||
|
||||
// Population
|
||||
rural: Number, // Rural population
|
||||
urban: Number, // Urban population
|
||||
|
||||
// Other
|
||||
pole: [x, y], // Label position
|
||||
}
|
||||
],
|
||||
|
||||
// Markers (map annotations)
|
||||
markers: [
|
||||
{
|
||||
i: Number, // Unique ID
|
||||
type: String, // Marker type (volcano, monument, etc.)
|
||||
x: Number, // X coordinate
|
||||
y: Number, // Y coordinate
|
||||
cell: Number, // Cell index
|
||||
icon: String, // Icon identifier
|
||||
size: Number, // Icon size
|
||||
note: String, // Associated note text
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Biomes Data
|
||||
|
||||
The `biomesData` object defines biome properties:
|
||||
|
||||
```javascript
|
||||
biomesData = {
|
||||
i: [id0, id1, ...], // Biome IDs
|
||||
name: [...], // Human-readable names
|
||||
color: [...], // Display colors
|
||||
habitability: [...], // How suitable for settlements (0-100)
|
||||
iconsDensity: [...], // Density of relief icons
|
||||
icons: [...], // Icon sets to use
|
||||
cost: [...], // Movement cost multiplier
|
||||
biomesMartix: [...] // Temperature/precipitation mapping
|
||||
}
|
||||
```
|
||||
|
||||
### Standard Biomes
|
||||
|
||||
| ID | Name | Description |
|
||||
|----|------|-------------|
|
||||
| 1 | Marine | Ocean biome |
|
||||
| 2 | Hot desert | Arid, hot regions |
|
||||
| 3 | Cold desert | Arid, cold regions |
|
||||
| 4 | Savanna | Grasslands with scattered trees |
|
||||
| 5 | Grassland | Temperate grasslands |
|
||||
| 6 | Tropical seasonal forest | Wet/dry tropical forest |
|
||||
| 7 | Temperate deciduous forest | Moderate climate forests |
|
||||
| 8 | Tropical rainforest | Dense, wet jungle |
|
||||
| 9 | Temperate rainforest | Wet coastal forests |
|
||||
| 10 | Taiga | Boreal forest |
|
||||
| 11 | Tundra | Treeless cold regions |
|
||||
| 12 | Glacier | Ice and snow |
|
||||
| 13 | Wetland | Marshes and swamps |
|
||||
|
||||
## Notes Data
|
||||
|
||||
User annotations stored separately:
|
||||
|
||||
```javascript
|
||||
notes = [
|
||||
{
|
||||
id: String, // Unique identifier
|
||||
name: String, // Note title
|
||||
legend: String, // Legend text
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Map History
|
||||
|
||||
Undo/redo system stores state snapshots:
|
||||
|
||||
```javascript
|
||||
mapHistory = [
|
||||
{
|
||||
json: String, // Serialized map state
|
||||
options: Object, // Generation options at time
|
||||
version: String // Generator version
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Data Relationships
|
||||
|
||||
### Cell → Civilization Hierarchy
|
||||
|
||||
```
|
||||
Cell (pack.cells.i[cellId])
|
||||
├─ Burg (pack.cells.burg[cellId] → pack.burgs[burgId])
|
||||
├─ State (pack.cells.s[cellId] → pack.states[stateId])
|
||||
├─ Culture (pack.cells.culture[cellId] → pack.cultures[cultureId])
|
||||
├─ Religion (pack.cells.religion[cellId] → pack.religions[religionId])
|
||||
└─ Province (pack.cells.province[cellId] → pack.provinces[provinceId])
|
||||
```
|
||||
|
||||
### State Hierarchy
|
||||
|
||||
```
|
||||
State (pack.states[stateId])
|
||||
├─ Capital Burg (pack.states[stateId].capital → pack.burgs[burgId])
|
||||
├─ Culture (pack.states[stateId].culture → pack.cultures[cultureId])
|
||||
├─ Religion (pack.states[stateId].religion → pack.religions[religionId])
|
||||
├─ Provinces (pack.provinces.filter(p => p.state === stateId))
|
||||
└─ Burgs (pack.burgs.filter(b => b.state === stateId))
|
||||
```
|
||||
|
||||
### River Network
|
||||
|
||||
```
|
||||
River (pack.rivers[riverId])
|
||||
├─ Source Cell (pack.rivers[riverId].source)
|
||||
├─ Mouth Cell (pack.rivers[riverId].mouth)
|
||||
├─ Path Cells (pack.rivers[riverId].cells[])
|
||||
└─ Parent River (pack.rivers[riverId].parent for tributaries)
|
||||
```
|
||||
|
||||
## Data Access Patterns
|
||||
|
||||
### Finding data for a cell
|
||||
|
||||
```javascript
|
||||
// Given a cell index
|
||||
const cellId = 1234;
|
||||
|
||||
// Get basic terrain
|
||||
const height = pack.cells.h[cellId];
|
||||
const temperature = pack.cells.temp[cellId];
|
||||
const biome = pack.cells.biome[cellId];
|
||||
|
||||
// Get civilization
|
||||
const stateId = pack.cells.s[cellId];
|
||||
const cultureId = pack.cells.culture[cellId];
|
||||
const burgId = pack.cells.burg[cellId];
|
||||
|
||||
// Get full objects
|
||||
const state = pack.states[stateId];
|
||||
const culture = pack.cultures[cultureId];
|
||||
const burg = pack.burgs[burgId];
|
||||
```
|
||||
|
||||
### Finding all cells for an entity
|
||||
|
||||
```javascript
|
||||
// All cells belonging to a state
|
||||
const stateCells = pack.cells.i.filter(i => pack.cells.s[i] === stateId);
|
||||
|
||||
// All cells with a specific biome
|
||||
const biomeCells = pack.cells.i.filter(i => pack.cells.biome[i] === biomeId);
|
||||
|
||||
// All cells with rivers
|
||||
const riverCells = pack.cells.i.filter(i => pack.cells.r[i] > 0);
|
||||
```
|
||||
|
||||
### Iterating efficiently
|
||||
|
||||
```javascript
|
||||
// Using typed arrays directly (fastest)
|
||||
for (let i = 0; i < pack.cells.i.length; i++) {
|
||||
const cellId = pack.cells.i[i];
|
||||
const height = pack.cells.h[i];
|
||||
// Process cell...
|
||||
}
|
||||
|
||||
// Using filter + map (more readable)
|
||||
const mountainCells = pack.cells.i
|
||||
.filter(i => pack.cells.h[i] > 70)
|
||||
.map(i => ({
|
||||
id: i,
|
||||
x: pack.cells.p[i][0],
|
||||
y: pack.cells.p[i][1]
|
||||
}));
|
||||
```
|
||||
|
||||
## Serialization
|
||||
|
||||
### Save Format
|
||||
|
||||
Maps are saved as JSON with the following structure:
|
||||
|
||||
```javascript
|
||||
{
|
||||
info: {
|
||||
version: String, // Generator version
|
||||
description: String, // Map description
|
||||
exportedAt: String, // Timestamp
|
||||
mapName: String, // Map name
|
||||
width: Number, // Map width
|
||||
height: Number, // Map height
|
||||
seed: String // Random seed
|
||||
},
|
||||
settings: {}, // Generation options
|
||||
mapCoordinates: {}, // Coordinate system
|
||||
grid: {}, // Grid data
|
||||
pack: {}, // Pack data
|
||||
biomesData: {}, // Biome definitions
|
||||
notes: [], // User notes
|
||||
nameBases: [] // Name generation data
|
||||
}
|
||||
```
|
||||
|
||||
### Load Process
|
||||
|
||||
When loading a map:
|
||||
1. Parse JSON
|
||||
2. Restore typed arrays from regular arrays
|
||||
3. Run version migration if needed (via `versioning.js`)
|
||||
4. Restore global state
|
||||
5. Regenerate derived data if necessary
|
||||
6. Render to SVG
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Memory Usage
|
||||
|
||||
Typed arrays provide significant memory savings:
|
||||
- `Uint8Array`: 1 byte per element (0-255)
|
||||
- `Uint16Array`: 2 bytes per element (0-65,535)
|
||||
- `Int8Array`: 1 byte per element (-128-127)
|
||||
- `Float32Array`: 4 bytes per element
|
||||
|
||||
For 10,000 cells:
|
||||
- Regular array: ~80 KB per property
|
||||
- Uint8Array: ~10 KB per property
|
||||
- **80-90% memory reduction**
|
||||
|
||||
### Access Speed
|
||||
|
||||
Typed arrays provide:
|
||||
- Faster iteration (predictable memory layout)
|
||||
- Better cache utilization
|
||||
- Optimized by JavaScript engines
|
||||
|
||||
### Trade-offs
|
||||
|
||||
**Pros:**
|
||||
- Excellent memory efficiency
|
||||
- Fast array operations
|
||||
- Type safety for numeric data
|
||||
|
||||
**Cons:**
|
||||
- Less flexible than objects
|
||||
- Parallel arrays can be confusing
|
||||
- Requires index synchronization
|
||||
|
||||
## Extending the Data Model
|
||||
|
||||
When adding new data:
|
||||
|
||||
1. **Choose the right location**
|
||||
- Cell-level: Add to `pack.cells.*`
|
||||
- Entity-level: Add new array like `pack.newEntities[]`
|
||||
|
||||
2. **Use appropriate types**
|
||||
- IDs: Uint16Array or Uint32Array
|
||||
- Small numbers: Uint8Array or Int8Array
|
||||
- Decimals: Float32Array
|
||||
- Strings/objects: Regular arrays
|
||||
|
||||
3. **Update serialization**
|
||||
- Add to save format
|
||||
- Add to load process
|
||||
- Handle versioning in `versioning.js`
|
||||
|
||||
4. **Consider relationships**
|
||||
- How does it relate to existing data?
|
||||
- What indices/lookups are needed?
|
||||
- How will it be queried?
|
||||
|
||||
### Example: Adding a new cell property
|
||||
|
||||
```javascript
|
||||
// 1. Add to pack.cells
|
||||
pack.cells.myProperty = new Uint8Array(pack.cells.i.length);
|
||||
|
||||
// 2. Initialize during generation
|
||||
function generateMyProperty() {
|
||||
for (let i = 0; i < pack.cells.i.length; i++) {
|
||||
pack.cells.myProperty[i] = calculateValue(i);
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Update save/load
|
||||
function saveMap() {
|
||||
const data = {
|
||||
// ... existing data
|
||||
myProperty: Array.from(pack.cells.myProperty)
|
||||
};
|
||||
}
|
||||
|
||||
function loadMap(data) {
|
||||
// ... load other data
|
||||
pack.cells.myProperty = new Uint8Array(data.myProperty);
|
||||
}
|
||||
|
||||
// 4. Use in rendering/editing
|
||||
function renderMyProperty() {
|
||||
d3.select('#myLayer').selectAll('path')
|
||||
.data(pack.cells.i)
|
||||
.attr('fill', i => getColor(pack.cells.myProperty[i]));
|
||||
}
|
||||
```
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
For more details on specific aspects:
|
||||
- [Architecture](Architecture.md) - System design and patterns
|
||||
- [Generation Process](Generation-Process.md) - How data is created
|
||||
- [Modules Reference](Modules-Reference.md) - Module APIs
|
||||
911
wiki/Features-and-UI.md
Normal file
911
wiki/Features-and-UI.md
Normal file
|
|
@ -0,0 +1,911 @@
|
|||
# Features and User Interface
|
||||
|
||||
This document describes all features available in the Fantasy Map Generator and how to use the user interface.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Main Interface](#main-interface)
|
||||
2. [Generation Features](#generation-features)
|
||||
3. [Editing Features](#editing-features)
|
||||
4. [Visualization Features](#visualization-features)
|
||||
5. [Export and Save Features](#export-and-save-features)
|
||||
6. [Advanced Features](#advanced-features)
|
||||
|
||||
---
|
||||
|
||||
## Main Interface
|
||||
|
||||
### Map Canvas
|
||||
|
||||
The central SVG canvas displays your generated map with multiple layers:
|
||||
|
||||
**Layer Controls:**
|
||||
- Toggle layers on/off using toolbar buttons
|
||||
- Adjust layer opacity
|
||||
- Reorder layers (z-index)
|
||||
|
||||
**Interaction:**
|
||||
- **Pan**: Click and drag
|
||||
- **Zoom**: Mouse wheel or pinch gesture
|
||||
- **Select**: Click on elements to select
|
||||
- **Info**: Hover for tooltips
|
||||
|
||||
### Toolbar
|
||||
|
||||
Located at the top of the screen, provides quick access to:
|
||||
|
||||
**File Operations:**
|
||||
- New map
|
||||
- Open map
|
||||
- Save map
|
||||
- Export
|
||||
|
||||
**Tools:**
|
||||
- Edit mode toggle
|
||||
- Layer visibility
|
||||
- Zoom controls
|
||||
- Fullscreen
|
||||
|
||||
**Options:**
|
||||
- Generation options
|
||||
- Style settings
|
||||
- Editor access
|
||||
|
||||
### Tools Panel
|
||||
|
||||
Expandable side panel with:
|
||||
- Quick generation options
|
||||
- Layer toggles
|
||||
- Minimap
|
||||
- Statistics
|
||||
|
||||
---
|
||||
|
||||
## Generation Features
|
||||
|
||||
### Initial Map Generation
|
||||
|
||||
**Access:** File → Generate New Map
|
||||
|
||||
**Options:**
|
||||
|
||||
#### Seed Settings
|
||||
- **Seed**: Text string for reproducible generation
|
||||
- Leave blank for random
|
||||
- Share seeds to recreate maps
|
||||
- **Random Button**: Generate random seed
|
||||
|
||||
#### Template Selection
|
||||
- **Heightmap Template**: Choose terrain type
|
||||
- Pangea - Single large continent
|
||||
- Continents - Multiple landmasses
|
||||
- Archipelago - Many islands
|
||||
- Atoll - Ring-shaped coral island
|
||||
- Mediterranean - Central sea
|
||||
- Peninsula - Land projection
|
||||
- Isthmus - Narrow land bridge
|
||||
- Volcano - Volcanic island
|
||||
- High/Low Island - Island types
|
||||
- Custom - Upload your own heightmap image
|
||||
|
||||
#### World Settings
|
||||
- **Cell Count**: Map detail level (1,000 - 100,000)
|
||||
- Lower = faster, less detailed
|
||||
- Higher = slower, more detailed
|
||||
- Default: ~10,000
|
||||
- **Map Size**: Width and height in pixels
|
||||
- **Latitude**: North/south positioning (affects climate)
|
||||
|
||||
#### Culture Settings
|
||||
- **Culture Count**: Number of cultures (1-20)
|
||||
- **Name Bases**: Select language/naming styles
|
||||
|
||||
#### State Settings
|
||||
- **State Count**: Number of political entities
|
||||
- **Expansionism**: How aggressively states expand
|
||||
- **Neutral Lands**: Percentage of unclaimed territory
|
||||
|
||||
#### Population Settings
|
||||
- **Urban Density**: Frequency of cities/towns
|
||||
- **Rural Density**: Population distribution
|
||||
- **Urban Growth**: City size multiplier
|
||||
|
||||
**Generate Button**: Start map generation with selected options
|
||||
|
||||
---
|
||||
|
||||
### Quick Regeneration
|
||||
|
||||
**Access:** Tools → Regenerate
|
||||
|
||||
Quickly regenerate specific map aspects:
|
||||
|
||||
- **Regenerate Cultures**: New culture distribution
|
||||
- **Regenerate States**: New political boundaries
|
||||
- **Regenerate Religions**: New religious landscape
|
||||
- **Regenerate Burgs**: New settlement locations
|
||||
- **Regenerate Rivers**: New river networks
|
||||
- **Regenerate Routes**: New road networks
|
||||
|
||||
Useful for refining maps without starting over.
|
||||
|
||||
---
|
||||
|
||||
## Editing Features
|
||||
|
||||
The generator includes 41+ specialized editors for fine-tuning every aspect of your map.
|
||||
|
||||
### Terrain Editing
|
||||
|
||||
#### Heightmap Editor
|
||||
|
||||
**Access:** Layers → Heightmap → Edit Heightmap
|
||||
|
||||
**Features:**
|
||||
- **Brush Tool**: Paint elevation
|
||||
- Adjustable size and strength
|
||||
- Raise or lower terrain
|
||||
- **Smooth Tool**: Soften elevation changes
|
||||
- **Flatten Tool**: Create plateaus
|
||||
- **Add/Remove Land**: Change coastlines
|
||||
- **Templates**: Apply heightmap patterns to regions
|
||||
- **Import Image**: Load custom heightmap
|
||||
|
||||
**Usage:**
|
||||
1. Select tool (brush, smooth, etc.)
|
||||
2. Adjust size and strength
|
||||
3. Click and drag on map
|
||||
4. Changes update in real-time
|
||||
|
||||
#### Biomes Editor
|
||||
|
||||
**Access:** Layers → Biomes → Edit Biomes
|
||||
|
||||
**Features:**
|
||||
- Change biome type for cells/regions
|
||||
- View biome distribution
|
||||
- Adjust climate parameters
|
||||
- Customize biome colors and properties
|
||||
|
||||
**Biome Types:**
|
||||
- Marine, Hot Desert, Cold Desert
|
||||
- Savanna, Grassland
|
||||
- Tropical Forest, Temperate Forest, Rainforest
|
||||
- Taiga, Tundra, Glacier
|
||||
- Wetland
|
||||
|
||||
#### Relief Editor
|
||||
|
||||
**Access:** Layers → Relief → Edit Relief
|
||||
|
||||
**Features:**
|
||||
- Add/remove terrain icons (mountains, hills, forests)
|
||||
- Adjust icon density
|
||||
- Change icon styles
|
||||
- Customize hill shading
|
||||
|
||||
---
|
||||
|
||||
### Water Features Editing
|
||||
|
||||
#### Rivers Editor
|
||||
|
||||
**Access:** Layers → Rivers → Edit Rivers
|
||||
|
||||
**Features:**
|
||||
- **Add River**: Click to create river source
|
||||
- **Remove River**: Delete rivers
|
||||
- **Regenerate River**: Recalculate specific river path
|
||||
- **Edit Path**: Modify river course
|
||||
- **Name Rivers**: Assign custom names
|
||||
- **Adjust Width**: Change river width
|
||||
|
||||
**River Properties:**
|
||||
- Name
|
||||
- Source and mouth
|
||||
- Length
|
||||
- Width
|
||||
- Type (river, stream, creek)
|
||||
- Parent (for tributaries)
|
||||
|
||||
#### Lakes Editor
|
||||
|
||||
**Access:** Layers → Lakes → Edit Lakes
|
||||
|
||||
**Features:**
|
||||
- Create new lakes
|
||||
- Remove lakes
|
||||
- Resize lakes
|
||||
- Name lakes
|
||||
- Adjust lake elevation
|
||||
|
||||
#### Coastline Editor
|
||||
|
||||
**Access:** Tools → Edit Coastline
|
||||
|
||||
**Features:**
|
||||
- Reshape coastlines
|
||||
- Add/remove coastal details
|
||||
- Create bays and peninsulas
|
||||
- Smooth jagged coasts
|
||||
|
||||
---
|
||||
|
||||
### Civilization Editing
|
||||
|
||||
#### Cultures Editor
|
||||
|
||||
**Access:** Layers → Cultures → Edit Cultures
|
||||
|
||||
**Features:**
|
||||
- **Add Culture**: Create new culture
|
||||
- **Remove Culture**: Delete culture
|
||||
- **Expand/Contract**: Adjust territory
|
||||
- **Properties**:
|
||||
- Name
|
||||
- Color
|
||||
- Name base (language)
|
||||
- Type (Generic, River, Lake, etc.)
|
||||
- Expansionism rate
|
||||
- Shield shape
|
||||
|
||||
**Culture List:**
|
||||
- View all cultures
|
||||
- See population and area
|
||||
- Filter by properties
|
||||
|
||||
#### States Editor
|
||||
|
||||
**Access:** Layers → States → Edit States
|
||||
|
||||
**Features:**
|
||||
- **Add State**: Create new state
|
||||
- **Remove State**: Delete state
|
||||
- **Merge States**: Combine multiple states
|
||||
- **Split State**: Divide into multiple states
|
||||
- **Change Capital**: Assign new capital city
|
||||
- **Adjust Borders**: Reshape boundaries
|
||||
|
||||
**State Properties:**
|
||||
- Name
|
||||
- Color
|
||||
- Capital burg
|
||||
- Government type (Kingdom, Empire, Republic, etc.)
|
||||
- Government form (Monarchy, Theocracy, etc.)
|
||||
- Culture
|
||||
- Religion
|
||||
- Expansionism
|
||||
- Military units
|
||||
- Diplomacy (relations with other states)
|
||||
|
||||
**Diplomacy:**
|
||||
- Set relations (Ally, Friendly, Neutral, Unfriendly, Enemy)
|
||||
- View diplomatic map
|
||||
|
||||
#### Burgs Editor (Settlements)
|
||||
|
||||
**Access:** Layers → Burgs → Edit Burgs
|
||||
|
||||
**Features:**
|
||||
- **Add Burg**: Place new settlement
|
||||
- **Remove Burg**: Delete settlement
|
||||
- **Move Burg**: Relocate settlement
|
||||
- **Properties**:
|
||||
- Name
|
||||
- Type (City, Town, Village)
|
||||
- Population
|
||||
- State
|
||||
- Culture
|
||||
- Capital status
|
||||
- Port/harbor
|
||||
- Citadel/fortress
|
||||
|
||||
**Settlement Types:**
|
||||
- **Capital**: State capital (largest)
|
||||
- **City**: Major urban center (10,000+)
|
||||
- **Town**: Smaller settlement (1,000-10,000)
|
||||
- **Village**: Small settlement (<1,000)
|
||||
|
||||
**Population:**
|
||||
- Manually set population
|
||||
- Auto-calculate based on surroundings
|
||||
- View urban vs. rural population
|
||||
|
||||
#### Religions Editor
|
||||
|
||||
**Access:** Layers → Religions → Edit Religions
|
||||
|
||||
**Features:**
|
||||
- **Add Religion**: Create new religion
|
||||
- **Remove Religion**: Delete religion
|
||||
- **Expand/Contract**: Adjust territory
|
||||
- **Properties**:
|
||||
- Name
|
||||
- Color
|
||||
- Type (Folk, Organized, Cult, Heresy)
|
||||
- Form (Cult, Church, Temple, etc.)
|
||||
- Origin culture
|
||||
- Deity name (if applicable)
|
||||
- Expansion strategy
|
||||
|
||||
#### Provinces Editor
|
||||
|
||||
**Access:** Layers → Provinces → Edit Provinces
|
||||
|
||||
**Features:**
|
||||
- Add/remove provinces
|
||||
- Adjust provincial boundaries
|
||||
- Assign provincial capitals
|
||||
- Name provinces
|
||||
- View province statistics
|
||||
|
||||
**Province Properties:**
|
||||
- Name
|
||||
- Form name (Duchy, County, Prefecture, etc.)
|
||||
- State
|
||||
- Capital burg
|
||||
- Area
|
||||
- Population
|
||||
|
||||
---
|
||||
|
||||
### Infrastructure Editing
|
||||
|
||||
#### Routes Editor
|
||||
|
||||
**Access:** Layers → Routes → Edit Routes
|
||||
|
||||
**Features:**
|
||||
- **Add Route**: Create road/trail/sea route
|
||||
- **Remove Route**: Delete route
|
||||
- **Regenerate Routes**: Recalculate optimal paths
|
||||
- **Edit Path**: Modify route course
|
||||
|
||||
**Route Types:**
|
||||
- **Roads**: Major land routes (black lines)
|
||||
- **Trails**: Minor paths (dashed lines)
|
||||
- **Sea Routes**: Maritime trade routes (blue lines)
|
||||
|
||||
**Properties:**
|
||||
- Connected burgs
|
||||
- Length
|
||||
- Width/importance
|
||||
- Path points
|
||||
|
||||
#### Military Overview
|
||||
|
||||
**Access:** Tools → Military
|
||||
|
||||
**Features:**
|
||||
- View all military units
|
||||
- Add/remove units
|
||||
- Assign units to burgs
|
||||
- Calculate military strength
|
||||
|
||||
**Unit Properties:**
|
||||
- Name
|
||||
- Type (Infantry, Cavalry, Archers, Artillery, Fleet)
|
||||
- Strength (number of soldiers)
|
||||
- State
|
||||
- Location (burg)
|
||||
|
||||
---
|
||||
|
||||
### Annotations and Markers
|
||||
|
||||
#### Markers Editor
|
||||
|
||||
**Access:** Layers → Markers → Edit Markers
|
||||
|
||||
**Features:**
|
||||
- **Add Marker**: Place custom markers
|
||||
- **Remove Marker**: Delete markers
|
||||
- **Properties**:
|
||||
- Type (volcano, ruins, mine, bridge, etc.)
|
||||
- Icon
|
||||
- Size
|
||||
- Associated note
|
||||
|
||||
**Marker Types:**
|
||||
- Volcanoes 🌋
|
||||
- Ruins 🏛️
|
||||
- Battlefields ⚔️
|
||||
- Mines ⛏️
|
||||
- Bridges 🌉
|
||||
- Monuments 🗿
|
||||
- Shrines ⛩️
|
||||
- Castles 🏰
|
||||
- Capitals ⭐
|
||||
|
||||
#### Notes Editor
|
||||
|
||||
**Access:** Tools → Notes
|
||||
|
||||
**Features:**
|
||||
- **Add Note**: Create text annotation
|
||||
- **Edit Note**: Modify note text
|
||||
- **Pin to Location**: Associate with marker/location
|
||||
- **Categories**: Organize notes by type
|
||||
|
||||
**Note Properties:**
|
||||
- Title
|
||||
- Description (rich text)
|
||||
- Legend text
|
||||
- Associated markers
|
||||
|
||||
#### Zones Editor
|
||||
|
||||
**Access:** Layers → Zones
|
||||
|
||||
**Features:**
|
||||
- Define custom zones/regions
|
||||
- Outline areas for campaigns
|
||||
- Mark territories
|
||||
- Add zone labels
|
||||
|
||||
---
|
||||
|
||||
## Visualization Features
|
||||
|
||||
### Style Editor
|
||||
|
||||
**Access:** Style → Edit Style
|
||||
|
||||
**Features:**
|
||||
|
||||
#### Color Schemes
|
||||
- **Terrain**: Heightmap coloring
|
||||
- **States**: Political boundaries
|
||||
- **Cultures**: Cultural regions
|
||||
- **Religions**: Religious distribution
|
||||
- **Biomes**: Vegetation zones
|
||||
|
||||
#### Presets
|
||||
- Default
|
||||
- Antique
|
||||
- Monochrome
|
||||
- Watercolor
|
||||
- And more...
|
||||
|
||||
#### Customization
|
||||
- Background color
|
||||
- Ocean color
|
||||
- Land gradient
|
||||
- Border styles
|
||||
- Label fonts and sizes
|
||||
|
||||
### Label Settings
|
||||
|
||||
**Access:** Style → Labels
|
||||
|
||||
**Features:**
|
||||
- **Show/Hide Labels**: Toggle label types
|
||||
- State names
|
||||
- Burg names
|
||||
- Province names
|
||||
- River names
|
||||
- Region names
|
||||
- **Font Settings**:
|
||||
- Font family
|
||||
- Font size
|
||||
- Font style (bold, italic)
|
||||
- Text color
|
||||
- Stroke color and width
|
||||
- **Label Positioning**: Auto or manual placement
|
||||
|
||||
### Layer Visibility
|
||||
|
||||
**Access:** Toolbar layer buttons
|
||||
|
||||
**Toggleable Layers:**
|
||||
- Terrain (heightmap)
|
||||
- Biomes
|
||||
- States
|
||||
- Cultures
|
||||
- Religions
|
||||
- Provinces
|
||||
- Borders
|
||||
- Rivers
|
||||
- Lakes
|
||||
- Coastline
|
||||
- Routes (roads, trails, sea routes)
|
||||
- Burgs (settlements)
|
||||
- Icons (relief icons)
|
||||
- Markers
|
||||
- Labels
|
||||
- Temperature (overlay)
|
||||
- Precipitation (overlay)
|
||||
- Population (density overlay)
|
||||
- Grid
|
||||
- Coordinates
|
||||
- Scale bar
|
||||
- Compass
|
||||
- Legend
|
||||
|
||||
---
|
||||
|
||||
### Temperature and Precipitation
|
||||
|
||||
**Access:** Layers → Temperature / Precipitation
|
||||
|
||||
**Features:**
|
||||
- View temperature distribution
|
||||
- View precipitation patterns
|
||||
- Adjust climate parameters
|
||||
- See climate effects on biomes
|
||||
|
||||
**Display:**
|
||||
- Heat map overlay
|
||||
- Gradient visualization
|
||||
- Isolines
|
||||
|
||||
---
|
||||
|
||||
### 3D View
|
||||
|
||||
**Access:** Tools → 3D View
|
||||
|
||||
**Features:**
|
||||
- 3D terrain visualization
|
||||
- Rotate and zoom
|
||||
- Adjust elevation exaggeration
|
||||
- Change lighting angle
|
||||
- Export 3D view
|
||||
|
||||
**Controls:**
|
||||
- Mouse drag to rotate
|
||||
- Scroll to zoom
|
||||
- Sliders for parameters
|
||||
|
||||
---
|
||||
|
||||
### Emblems and Heraldry
|
||||
|
||||
**Access:** Click on state/burg/province
|
||||
|
||||
**Features:**
|
||||
- View coat of arms
|
||||
- Regenerate heraldry
|
||||
- Customize elements:
|
||||
- Shield shape
|
||||
- Divisions
|
||||
- Charges (symbols)
|
||||
- Tinctures (colors)
|
||||
|
||||
**Heraldic Elements:**
|
||||
- 200+ charges (lions, eagles, crowns, etc.)
|
||||
- Multiple shield shapes
|
||||
- Standard heraldic rules
|
||||
- Export as SVG/PNG
|
||||
|
||||
---
|
||||
|
||||
## Export and Save Features
|
||||
|
||||
### Save Map
|
||||
|
||||
**Access:** File → Save Map
|
||||
|
||||
**Formats:**
|
||||
- **.map** - Native format (includes all data)
|
||||
- Compressed JSON
|
||||
- Can be loaded later
|
||||
|
||||
**Features:**
|
||||
- Auto-save to browser storage
|
||||
- Manual save to file
|
||||
- Save to cloud (Dropbox integration)
|
||||
|
||||
---
|
||||
|
||||
### Load Map
|
||||
|
||||
**Access:** File → Load Map
|
||||
|
||||
**Sources:**
|
||||
- Local file
|
||||
- URL
|
||||
- Dropbox
|
||||
- Browser storage (auto-saved)
|
||||
|
||||
**Compatibility:**
|
||||
- Automatic version migration
|
||||
- Handles old map formats
|
||||
- Validates data integrity
|
||||
|
||||
---
|
||||
|
||||
### Export Options
|
||||
|
||||
**Access:** File → Export
|
||||
|
||||
#### Export SVG
|
||||
|
||||
- Vector format
|
||||
- Scalable without quality loss
|
||||
- Edit in Inkscape, Illustrator, etc.
|
||||
- Options:
|
||||
- All layers or selected layers
|
||||
- Embedded fonts
|
||||
- Optimized output
|
||||
|
||||
#### Export PNG
|
||||
|
||||
- Raster format
|
||||
- High resolution available
|
||||
- Options:
|
||||
- Resolution (DPI)
|
||||
- Size (width × height)
|
||||
- Quality
|
||||
- Transparent background
|
||||
|
||||
#### Export JSON
|
||||
|
||||
- Raw data export
|
||||
- All map data in JSON format
|
||||
- Use for custom processing
|
||||
- Import into other tools
|
||||
|
||||
#### Export Other Formats
|
||||
|
||||
- **PDF**: Print-ready format
|
||||
- **CSV**: Data tables (burgs, states, etc.)
|
||||
- **GeoJSON**: Geographic data format
|
||||
|
||||
---
|
||||
|
||||
### Print Map
|
||||
|
||||
**Access:** File → Print
|
||||
|
||||
**Features:**
|
||||
- Print-optimized layout
|
||||
- Paper size selection
|
||||
- Scale adjustment
|
||||
- Layer selection
|
||||
- Preview before printing
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Submaps
|
||||
|
||||
**Access:** Tools → Create Submap
|
||||
|
||||
**Purpose:** Generate detailed map of a specific region
|
||||
|
||||
**Features:**
|
||||
- Select region on main map
|
||||
- Generate high-detail submap
|
||||
- Inherit terrain and features
|
||||
- Independent editing
|
||||
|
||||
**Use Cases:**
|
||||
- Zooming into a kingdom
|
||||
- Detailed city surroundings
|
||||
- Regional campaigns
|
||||
|
||||
---
|
||||
|
||||
### Focus Mode
|
||||
|
||||
**Access:** Tools → Focus
|
||||
|
||||
**Features:**
|
||||
- **Focus on Cell**: Zoom to specific cell
|
||||
- **Focus on Burg**: Center on settlement
|
||||
- **Focus on Coordinates**: Go to X, Y position
|
||||
|
||||
---
|
||||
|
||||
### Elevation Profile
|
||||
|
||||
**Access:** Tools → Elevation Profile
|
||||
|
||||
**Features:**
|
||||
- Draw line on map
|
||||
- View elevation graph along line
|
||||
- Measure distance
|
||||
- Identify peaks and valleys
|
||||
|
||||
---
|
||||
|
||||
### Battle Screen
|
||||
|
||||
**Access:** Tools → Battle Screen
|
||||
|
||||
**Features:**
|
||||
- Tactical battle map view
|
||||
- Hexagonal grid overlay
|
||||
- Unit placement
|
||||
- Terrain effects
|
||||
|
||||
---
|
||||
|
||||
### Customization
|
||||
|
||||
#### Custom Name Bases
|
||||
|
||||
**Access:** Tools → Name Bases
|
||||
|
||||
**Features:**
|
||||
- Add custom language/naming
|
||||
- Provide example names
|
||||
- Generator learns patterns
|
||||
- Apply to cultures
|
||||
|
||||
#### Custom Biomes
|
||||
|
||||
**Access:** Biomes → Customize
|
||||
|
||||
**Features:**
|
||||
- Define new biome types
|
||||
- Set climate parameters
|
||||
- Assign colors and icons
|
||||
- Adjust habitability
|
||||
|
||||
---
|
||||
|
||||
### Versioning
|
||||
|
||||
**Access:** Automatic
|
||||
|
||||
**Features:**
|
||||
- Maps store version info
|
||||
- Auto-upgrade on load
|
||||
- Maintains compatibility
|
||||
- Migration scripts for old maps
|
||||
|
||||
Handled by `versioning.js`.
|
||||
|
||||
---
|
||||
|
||||
### Undo/Redo
|
||||
|
||||
**Access:** Edit menu or Ctrl+Z / Ctrl+Y
|
||||
|
||||
**Features:**
|
||||
- Undo recent changes
|
||||
- Redo undone changes
|
||||
- History tracking
|
||||
- Multiple undo levels
|
||||
|
||||
---
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
**Common Shortcuts:**
|
||||
- **Ctrl+Z**: Undo
|
||||
- **Ctrl+Y**: Redo
|
||||
- **Ctrl+S**: Save map
|
||||
- **Ctrl+O**: Open map
|
||||
- **F11**: Fullscreen
|
||||
- **Space**: Pan mode
|
||||
- **+/-**: Zoom in/out
|
||||
- **Esc**: Cancel current operation
|
||||
|
||||
---
|
||||
|
||||
### Map Statistics
|
||||
|
||||
**Access:** Tools → Statistics
|
||||
|
||||
**Features:**
|
||||
- Total land area
|
||||
- Total population
|
||||
- Number of states
|
||||
- Number of burgs
|
||||
- Culture distribution
|
||||
- Religion distribution
|
||||
- Biome distribution
|
||||
- And more...
|
||||
|
||||
**Export:** Export statistics as CSV/JSON
|
||||
|
||||
---
|
||||
|
||||
### Randomization Tools
|
||||
|
||||
**Access:** Tools → Randomize
|
||||
|
||||
**Features:**
|
||||
- Randomize names (burgs, states, etc.)
|
||||
- Randomize colors
|
||||
- Randomize coats of arms
|
||||
- Randomize any specific aspect
|
||||
|
||||
Useful for quickly generating variations.
|
||||
|
||||
---
|
||||
|
||||
## Tips and Tricks
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
1. **Lower cell count** for faster generation
|
||||
2. **Disable unused layers** for better rendering
|
||||
3. **Use simple styles** for complex maps
|
||||
4. **Close editors** when not in use
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Save frequently** to avoid data loss
|
||||
2. **Use seeds** for reproducibility
|
||||
3. **Start with templates** then customize
|
||||
4. **Layer edits** progressively (terrain → cultures → states)
|
||||
5. **Backup important maps**
|
||||
|
||||
### Common Workflows
|
||||
|
||||
#### Creating a Campaign Map
|
||||
|
||||
1. Generate base map with template
|
||||
2. Adjust terrain with heightmap editor
|
||||
3. Refine rivers and lakes
|
||||
4. Edit culture and state boundaries
|
||||
5. Add important cities/locations
|
||||
6. Place markers for quest locations
|
||||
7. Add notes for lore
|
||||
8. Style and export
|
||||
|
||||
#### Creating a World Map
|
||||
|
||||
1. Use "Continents" template
|
||||
2. Generate with medium cell count
|
||||
3. Focus on large-scale features
|
||||
4. Simplify details (fewer burgs)
|
||||
5. Adjust states for empires/kingdoms
|
||||
6. Export at high resolution
|
||||
|
||||
#### Creating a Regional Map
|
||||
|
||||
1. Use "Peninsula" or custom template
|
||||
2. High cell count for detail
|
||||
3. Add many burgs
|
||||
4. Detailed provinces
|
||||
5. Add markers for every point of interest
|
||||
6. Extensive notes and lore
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Map Won't Generate:**
|
||||
- Check browser console for errors
|
||||
- Try lower cell count
|
||||
- Use different template
|
||||
- Clear browser cache
|
||||
|
||||
**Performance Issues:**
|
||||
- Reduce cell count
|
||||
- Disable complex layers
|
||||
- Close other browser tabs
|
||||
- Use modern browser
|
||||
|
||||
**Export Not Working:**
|
||||
- Check browser permissions
|
||||
- Try different format
|
||||
- Reduce export size
|
||||
- Update browser
|
||||
|
||||
**Data Loss:**
|
||||
- Check auto-save in browser storage
|
||||
- Look for backup files
|
||||
- Enable cloud save
|
||||
|
||||
For more help:
|
||||
- [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues)
|
||||
- [Discord Community](https://discordapp.com/invite/X7E84HU)
|
||||
- [Reddit Community](https://www.reddit.com/r/FantasyMapGenerator)
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Generation Process](Generation-Process.md) - How maps are created
|
||||
- [Data Model](Data-Model.md) - Understanding the data
|
||||
- [Modules Reference](Modules-Reference.md) - Technical details
|
||||
- [Architecture](Architecture.md) - System design
|
||||
805
wiki/Generation-Process.md
Normal file
805
wiki/Generation-Process.md
Normal file
|
|
@ -0,0 +1,805 @@
|
|||
# Map Generation Process
|
||||
|
||||
This document explains how the Fantasy Map Generator creates maps, describing each step of the generation pipeline in detail.
|
||||
|
||||
## Overview
|
||||
|
||||
Map generation is a multi-stage process where each stage builds upon the previous one. The entire process is orchestrated by the `generate()` function in `main.js`.
|
||||
|
||||
## Generation Pipeline
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 1. Initialization │
|
||||
│ • Set random seed │
|
||||
│ • Apply map size and options │
|
||||
│ • Initialize data structures │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 2. Grid Generation │
|
||||
│ • Create jittered point grid │
|
||||
│ • Generate Voronoi diagram via Delaunay triangulation │
|
||||
│ • ~10,000 cells by default │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 3. Heightmap Generation │
|
||||
│ • Generate terrain elevation (0-100) │
|
||||
│ • Use templates or custom heightmaps │
|
||||
│ • Sea level typically at 20 │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 4. Feature Detection │
|
||||
│ • Identify land vs water │
|
||||
│ • Detect islands, continents, oceans │
|
||||
│ • Mark coastal cells │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 5. Climate Calculation │
|
||||
│ • Calculate temperature (latitude-based) │
|
||||
│ • Generate precipitation patterns │
|
||||
│ • Wind and moisture simulation │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 6. Repack Grid │
|
||||
│ • Filter land cells from grid │
|
||||
│ • Create pack structure │
|
||||
│ • Add additional cell properties │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 7. Water Features │
|
||||
│ • Draw coastlines │
|
||||
│ • Generate rivers (flux calculation + flow) │
|
||||
│ • Create lakes in depressions │
|
||||
│ • Define lake groups │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 8. Biome Assignment │
|
||||
│ • Map temperature + precipitation to biomes │
|
||||
│ • 13 biome types (desert, forest, tundra, etc.) │
|
||||
│ • Store in pack.cells.biome │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 9. Cell Ranking │
|
||||
│ • Calculate cell suitability for settlement │
|
||||
│ • Based on terrain, biome, rivers, coasts │
|
||||
│ • Used for placement of towns/cities │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 10. Culture Generation │
|
||||
│ • Place culture centers │
|
||||
│ • Expand cultures across suitable cells │
|
||||
│ • Assign name generation bases │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 11. Burgs and States │
|
||||
│ • Place capital cities │
|
||||
│ • Generate states around capitals │
|
||||
│ • Add secondary towns │
|
||||
│ • Define state boundaries │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 12. Religion Generation │
|
||||
│ • Create religions from cultures │
|
||||
│ • Spread religions across territories │
|
||||
│ • Assign state religions │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 13. Provinces │
|
||||
│ • Divide states into provinces │
|
||||
│ • Assign provincial capitals │
|
||||
│ • Define provincial boundaries │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 14. Route Generation │
|
||||
│ • Create road networks between burgs │
|
||||
│ • Generate sea routes │
|
||||
│ • Add trails to secondary locations │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 15. Military Generation │
|
||||
│ • Create military units for states │
|
||||
│ • Assign regiments to burgs │
|
||||
│ • Calculate military strength │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 16. Marker Generation │
|
||||
│ • Place special markers (volcanoes, ruins, etc.) │
|
||||
│ • Add points of interest │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────────────────────┐
|
||||
│ 17. Rendering │
|
||||
│ • Draw all map layers to SVG │
|
||||
│ • Render states, borders, labels │
|
||||
│ • Apply styling │
|
||||
│ • Add UI elements (scale, compass, legend) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Detailed Stage Descriptions
|
||||
|
||||
### 1. Initialization
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `generate()`
|
||||
|
||||
```javascript
|
||||
async function generate(options) {
|
||||
seed = generateSeed();
|
||||
Math.random = aleaPRNG(seed); // Set seeded RNG
|
||||
applyGraphSize(); // Set SVG dimensions
|
||||
randomizeOptions(); // Initialize generation parameters
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose:**
|
||||
- Establishes random seed for reproducibility
|
||||
- Sets map dimensions (width, height)
|
||||
- Initializes generation options (templates, settings)
|
||||
|
||||
**Seed:**
|
||||
- Can be user-specified or randomly generated
|
||||
- Ensures identical maps can be regenerated
|
||||
- Format: Short string (e.g., "abc123")
|
||||
|
||||
### 2. Grid Generation
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `generateGrid()`
|
||||
|
||||
```javascript
|
||||
function generateGrid() {
|
||||
const points = generateJitteredPoints(cellsDesired);
|
||||
const delaunay = Delaunator.from(points);
|
||||
const voronoi = new Voronoi(delaunay, points);
|
||||
grid = voronoi.toGrid();
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose:**
|
||||
- Creates the spatial data structure for the map
|
||||
- Divides map into cells using Voronoi diagram
|
||||
|
||||
**Process:**
|
||||
1. Generate ~10,000 points in a jittered grid pattern
|
||||
2. Create Delaunay triangulation from points
|
||||
3. Compute dual Voronoi diagram
|
||||
4. Store in `grid` object
|
||||
|
||||
**Why Voronoi?**
|
||||
- Natural-looking irregular cells
|
||||
- Efficient neighbor lookups
|
||||
- Well-suited for procedural generation
|
||||
|
||||
### 3. Heightmap Generation
|
||||
|
||||
**File:** `modules/heightmap-generator.js`
|
||||
**Module:** `HeightmapGenerator`
|
||||
|
||||
```javascript
|
||||
await HeightmapGenerator.generate();
|
||||
```
|
||||
|
||||
**Templates Available:**
|
||||
- **Pangea** - Single large continent
|
||||
- **Archipelago** - Many islands
|
||||
- **Atoll** - Ring-shaped island
|
||||
- **Continents** - Multiple landmasses
|
||||
- **High Island** - Volcanic island
|
||||
- **Low Island** - Flat coral island
|
||||
- **And more...**
|
||||
|
||||
**Process:**
|
||||
1. Select template or use custom heightmap
|
||||
2. Apply template algorithm to assign elevations
|
||||
3. Smooth and add noise for realism
|
||||
4. Normalize values to 0-100 range
|
||||
5. Store in `grid.cells.h`
|
||||
|
||||
**Height Conventions:**
|
||||
- `0-19`: Water (ocean/lakes)
|
||||
- `20`: Sea level
|
||||
- `20-30`: Coastal lowlands
|
||||
- `30-50`: Plains
|
||||
- `50-70`: Hills
|
||||
- `70+`: Mountains
|
||||
|
||||
### 4. Feature Detection
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `markFeatures()`
|
||||
|
||||
```javascript
|
||||
function markFeatures() {
|
||||
detectIslands();
|
||||
markOceans();
|
||||
markLakes();
|
||||
markCoastalCells();
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose:**
|
||||
- Identifies distinct geographic features
|
||||
- Labels landmasses and water bodies
|
||||
- Detects borders and coastlines
|
||||
|
||||
**Feature Types:**
|
||||
- **Islands/Continents**: Contiguous land areas
|
||||
- **Oceans**: Large water bodies touching borders
|
||||
- **Lakes**: Enclosed water bodies on land
|
||||
|
||||
Each feature gets a unique ID stored in `grid.cells.f`.
|
||||
|
||||
### 5. Climate Calculation
|
||||
|
||||
**File:** `main.js`
|
||||
**Functions:** `calculateTemperatures()`, `generatePrecipitation()`
|
||||
|
||||
**Temperature:**
|
||||
```javascript
|
||||
// Based on latitude
|
||||
const latitude = y / mapHeight; // 0 = north, 1 = south
|
||||
const temp = temperatureCurve(latitude, elevation);
|
||||
grid.cells.temp[i] = temp;
|
||||
```
|
||||
|
||||
Factors affecting temperature:
|
||||
- **Latitude** - Colder at poles, warmer at equator
|
||||
- **Elevation** - Decreases with height
|
||||
- **Ocean proximity** - Moderating effect
|
||||
|
||||
**Precipitation:**
|
||||
```javascript
|
||||
// Moisture from oceans, modified by prevailing winds
|
||||
const prec = calculateMoisture(cell, windDirection);
|
||||
grid.cells.prec[i] = prec;
|
||||
```
|
||||
|
||||
Factors affecting precipitation:
|
||||
- **Ocean proximity** - Higher near coasts
|
||||
- **Wind direction** - Prevailing winds bring moisture
|
||||
- **Elevation** - Rain shadow effects
|
||||
- **Temperature** - Warmer air holds more moisture
|
||||
|
||||
### 6. Repack Grid
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `reGraph()`
|
||||
|
||||
```javascript
|
||||
function reGraph() {
|
||||
pack.cells = filterLandCells(grid.cells);
|
||||
pack.vertices = grid.vertices;
|
||||
// Add additional properties...
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose:**
|
||||
- Creates optimized structure for land-only operations
|
||||
- Removes ocean cells to save memory
|
||||
- Adds civilization-related properties
|
||||
|
||||
**New Properties Added:**
|
||||
- `s` - State ID
|
||||
- `culture` - Culture ID
|
||||
- `religion` - Religion ID
|
||||
- `burg` - Settlement ID
|
||||
- `province` - Province ID
|
||||
- `road` - Road network
|
||||
- `pop` - Population density
|
||||
|
||||
### 7. Water Features
|
||||
|
||||
#### Coastline Drawing
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `drawCoastline()`
|
||||
|
||||
Renders coastlines to SVG for visualization.
|
||||
|
||||
#### River Generation
|
||||
|
||||
**File:** `modules/river-generator.js`
|
||||
**Module:** `Rivers.generate()`
|
||||
|
||||
```javascript
|
||||
Rivers.generate() {
|
||||
calculateFlux(); // Water accumulation
|
||||
createRiverPaths(); // Route rivers downhill
|
||||
applyDowncutting(); // Erosion simulation
|
||||
detectConfluence(); // Identify river junctions
|
||||
}
|
||||
```
|
||||
|
||||
**Flux Calculation:**
|
||||
- Each cell receives water from precipitation
|
||||
- Water flows to lowest adjacent cell
|
||||
- Accumulates creating river strength
|
||||
|
||||
**River Pathing:**
|
||||
- Start from high-flux cells
|
||||
- Follow elevation gradient downward
|
||||
- Terminate at ocean or lake
|
||||
- Tributaries merge into larger rivers
|
||||
|
||||
**Downcutting:**
|
||||
- Rivers erode terrain over time
|
||||
- Lowers elevation along river paths
|
||||
- Creates valleys and canyons
|
||||
|
||||
#### Lake Creation
|
||||
|
||||
**File:** `modules/lakes.js`
|
||||
**Module:** `Lakes.defineGroup()`
|
||||
|
||||
- Identifies water cells not connected to ocean
|
||||
- Groups adjacent lake cells
|
||||
- Names lakes
|
||||
- Calculates lake areas
|
||||
|
||||
### 8. Biome Assignment
|
||||
|
||||
**File:** `modules/biomes.js`
|
||||
**Module:** `Biomes.define()`
|
||||
|
||||
```javascript
|
||||
Biomes.define() {
|
||||
for (const cell of pack.cells.i) {
|
||||
const temp = pack.cells.temp[cell];
|
||||
const prec = pack.cells.prec[cell];
|
||||
const biome = biomeMatrix[temp][prec];
|
||||
pack.cells.biome[cell] = biome;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Biome Matrix:**
|
||||
Maps temperature + precipitation to biome types:
|
||||
|
||||
```
|
||||
Precipitation →
|
||||
Low Medium High
|
||||
┌──────────┬──────────┬──────────┐
|
||||
T Hot │ Desert │ Savanna │ Tropical │
|
||||
e ├──────────┼──────────┼──────────┤
|
||||
m Warm │Grassland │ Forest │Rainforest│
|
||||
p ├──────────┼──────────┼──────────┤
|
||||
↓ Cold │ Tundra │ Taiga │ Wetland │
|
||||
└──────────┴──────────┴──────────┘
|
||||
```
|
||||
|
||||
**13 Biome Types:**
|
||||
1. Marine (ocean)
|
||||
2. Hot desert
|
||||
3. Cold desert
|
||||
4. Savanna
|
||||
5. Grassland
|
||||
6. Tropical seasonal forest
|
||||
7. Temperate deciduous forest
|
||||
8. Tropical rainforest
|
||||
9. Temperate rainforest
|
||||
10. Taiga
|
||||
11. Tundra
|
||||
12. Glacier
|
||||
13. Wetland
|
||||
|
||||
### 9. Cell Ranking
|
||||
|
||||
**File:** `main.js`
|
||||
**Function:** `rankCells()`
|
||||
|
||||
```javascript
|
||||
function rankCells() {
|
||||
for (const cell of pack.cells.i) {
|
||||
let score = 0;
|
||||
score += biomeHabitability[pack.cells.biome[cell]];
|
||||
score += riverBonus[pack.cells.r[cell]];
|
||||
score += coastalBonus[isCoastal(cell)];
|
||||
score -= elevationPenalty[pack.cells.h[cell]];
|
||||
pack.cells.s[cell] = score;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Factors:**
|
||||
- **Biome habitability** - Forests good, deserts bad
|
||||
- **River proximity** - Rivers provide water and trade
|
||||
- **Coastal location** - Access to fishing and trade
|
||||
- **Elevation** - Lowlands preferred over mountains
|
||||
|
||||
**Used For:**
|
||||
- Selecting locations for towns and cities
|
||||
- Expanding cultures and states
|
||||
- Calculating population density
|
||||
|
||||
### 10. Culture Generation
|
||||
|
||||
**File:** `modules/cultures-generator.js`
|
||||
**Module:** `Cultures.generate()` and `Cultures.expand()`
|
||||
|
||||
**Generation Process:**
|
||||
|
||||
```javascript
|
||||
Cultures.generate() {
|
||||
const count = rn(5, 10); // 5-10 cultures
|
||||
for (let i = 0; i < count; i++) {
|
||||
const center = selectHighRankCell();
|
||||
const culture = createCulture(center);
|
||||
pack.cultures.push(culture);
|
||||
}
|
||||
}
|
||||
|
||||
Cultures.expand() {
|
||||
// Expand from centers using expansion algorithm
|
||||
for (const culture of pack.cultures) {
|
||||
expandFromCenter(culture, culture.expansionism);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Placement:**
|
||||
- Cultures start at high-rank cells
|
||||
- Multiple cultures per map (5-10 typical)
|
||||
|
||||
**Expansion:**
|
||||
- Spreads outward from origin
|
||||
- Prefers habitable terrain
|
||||
- Stops at natural barriers (oceans, mountains)
|
||||
- Fills until meeting other cultures
|
||||
|
||||
**Properties:**
|
||||
- Name (procedurally generated)
|
||||
- Color (for map display)
|
||||
- Name base (for generating place names)
|
||||
- Type (Generic, River, Lake, Naval, etc.)
|
||||
- Shield shape (for coat of arms)
|
||||
|
||||
### 11. Burgs and States
|
||||
|
||||
**File:** `modules/burgs-and-states.js`
|
||||
**Module:** `BurgsAndStates.generate()`
|
||||
|
||||
**Capital Placement:**
|
||||
|
||||
```javascript
|
||||
BurgsAndStates.generate() {
|
||||
// 1. Place capitals
|
||||
for (const culture of pack.cultures) {
|
||||
const capital = placeCapital(culture);
|
||||
pack.burgs.push(capital);
|
||||
}
|
||||
|
||||
// 2. Create states from capitals
|
||||
for (const capital of capitals) {
|
||||
const state = createState(capital);
|
||||
expandState(state);
|
||||
pack.states.push(state);
|
||||
}
|
||||
|
||||
// 3. Add secondary towns
|
||||
addSecondaryBurgs();
|
||||
}
|
||||
```
|
||||
|
||||
**Burg Types:**
|
||||
- **Capital** - State capital (largest city)
|
||||
- **City** - Major urban center
|
||||
- **Town** - Smaller settlement
|
||||
|
||||
**Burg Properties:**
|
||||
- Name (from culture's name base)
|
||||
- Population (based on rank + surroundings)
|
||||
- Type (city, town, etc.)
|
||||
- Port status (if coastal)
|
||||
- Citadel (defensive structures)
|
||||
|
||||
**State Creation:**
|
||||
- Each capital becomes center of a state
|
||||
- State expands to fill territory
|
||||
- Boundaries form where states meet
|
||||
- Neutral areas remain unclaimed
|
||||
|
||||
**State Properties:**
|
||||
- Name (from capital + government form)
|
||||
- Color (randomly assigned)
|
||||
- Type (Kingdom, Empire, Republic, etc.)
|
||||
- Culture (dominant culture)
|
||||
- Religion (state religion)
|
||||
- Expansionism (aggressiveness)
|
||||
|
||||
### 12. Religion Generation
|
||||
|
||||
**File:** `modules/religions-generator.js`
|
||||
**Module:** `Religions.generate()`
|
||||
|
||||
```javascript
|
||||
Religions.generate() {
|
||||
const count = rn(5, 10);
|
||||
for (let i = 0; i < count; i++) {
|
||||
const culture = selectRandomCulture();
|
||||
const religion = createReligion(culture);
|
||||
pack.religions.push(religion);
|
||||
expandReligion(religion);
|
||||
}
|
||||
assignStateReligions();
|
||||
}
|
||||
```
|
||||
|
||||
**Religion Types:**
|
||||
- Folk religions (localized)
|
||||
- Organized religions (widespread)
|
||||
- Cults (small followings)
|
||||
|
||||
**Expansion:**
|
||||
- Spreads from origin culture
|
||||
- Can cross state borders
|
||||
- Expansion rate varies by type
|
||||
- Some states adopt as official religion
|
||||
|
||||
### 13. Province Generation
|
||||
|
||||
**File:** `modules/burgs-and-states.js`
|
||||
**Module:** `BurgsAndStates.generateProvinces()`
|
||||
|
||||
```javascript
|
||||
BurgsAndStates.generateProvinces() {
|
||||
for (const state of pack.states) {
|
||||
const provinceCount = calculateProvinceCount(state.area);
|
||||
divideIntoProvinces(state, provinceCount);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Process:**
|
||||
- Larger states divided into provinces
|
||||
- Each province has a capital burg
|
||||
- Province boundaries respect state borders
|
||||
- Names generated from capitals + titles
|
||||
|
||||
### 14. Route Generation
|
||||
|
||||
**File:** `modules/routes-generator.js`
|
||||
**Module:** `Routes.generate()`
|
||||
|
||||
```javascript
|
||||
Routes.generate() {
|
||||
generateRoads(); // Land routes between burgs
|
||||
generateTrails(); // Secondary paths
|
||||
generateSeaRoutes(); // Maritime trade routes
|
||||
}
|
||||
```
|
||||
|
||||
**Road Generation:**
|
||||
- Connects burgs within states
|
||||
- Pathfinding considers terrain
|
||||
- Major roads between large cities
|
||||
- Secondary roads to smaller towns
|
||||
|
||||
**Sea Routes:**
|
||||
- Connects coastal burgs
|
||||
- Maritime trade routes
|
||||
- Follows coastlines or crosses seas
|
||||
|
||||
**Route Properties:**
|
||||
- Width/importance
|
||||
- Points along route
|
||||
- Connected burgs
|
||||
|
||||
### 15. Military Generation
|
||||
|
||||
**File:** `modules/military-generator.js`
|
||||
**Module:** `Military.generate()`
|
||||
|
||||
```javascript
|
||||
Military.generate() {
|
||||
for (const state of pack.states) {
|
||||
const unitCount = calculateUnits(state.population);
|
||||
for (let i = 0; i < unitCount; i++) {
|
||||
const unit = createMilitaryUnit(state);
|
||||
state.military.push(unit);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Military Units:**
|
||||
- Based on state population
|
||||
- Assigned to burgs
|
||||
- Types: infantry, cavalry, archers, etc.
|
||||
- Used for calculating state strength
|
||||
|
||||
### 16. Marker Generation
|
||||
|
||||
**File:** `modules/markers-generator.js`
|
||||
**Module:** `Markers.generate()`
|
||||
|
||||
```javascript
|
||||
Markers.generate() {
|
||||
placeVolcanoes();
|
||||
placeRuins();
|
||||
placeBattlefields();
|
||||
// ... other marker types
|
||||
}
|
||||
```
|
||||
|
||||
**Marker Types:**
|
||||
- Volcanoes (on mountains)
|
||||
- Ruins (ancient sites)
|
||||
- Battlefields (historical locations)
|
||||
- Monuments
|
||||
- Mines
|
||||
- Bridges
|
||||
- And more...
|
||||
|
||||
**Placement:**
|
||||
- Based on terrain suitability
|
||||
- Random with constraints
|
||||
- Can be manually added by users
|
||||
|
||||
### 17. Rendering
|
||||
|
||||
**File:** `main.js`
|
||||
**Multiple Functions:** `drawStates()`, `drawRivers()`, `drawLabels()`, etc.
|
||||
|
||||
```javascript
|
||||
function renderMap() {
|
||||
drawOcean();
|
||||
drawTerrain();
|
||||
drawBiomes();
|
||||
drawRivers();
|
||||
drawLakes();
|
||||
drawStates();
|
||||
drawBorders();
|
||||
drawRoutes();
|
||||
drawBurgs();
|
||||
drawLabels();
|
||||
drawIcons();
|
||||
drawScaleBar();
|
||||
drawCompass();
|
||||
}
|
||||
```
|
||||
|
||||
**Rendering Process:**
|
||||
- Uses D3.js for SVG manipulation
|
||||
- Layers drawn in order (back to front)
|
||||
- Styling applied from templates
|
||||
- Interactive elements attached
|
||||
|
||||
**Performance:**
|
||||
- Selective layer updates
|
||||
- Efficient D3 data binding
|
||||
- Minimal redraws during editing
|
||||
|
||||
## Generation Options
|
||||
|
||||
Users can customize generation through various options:
|
||||
|
||||
### Heightmap Options
|
||||
- **Template** - Select terrain type
|
||||
- **Custom Image** - Upload heightmap
|
||||
- **Seed** - Reproducible generation
|
||||
|
||||
### World Options
|
||||
- **Cell Count** - Map detail level
|
||||
- **Map Size** - Width and height
|
||||
- **Randomize** - Randomize all settings
|
||||
|
||||
### Culture Options
|
||||
- **Culture Count** - Number of cultures
|
||||
- **Name Bases** - Language/naming styles
|
||||
|
||||
### State Options
|
||||
- **State Count** - Number of states
|
||||
- **Expansionism** - Aggression levels
|
||||
|
||||
### Population Options
|
||||
- **Urban Density** - City frequency
|
||||
- **Rural Density** - Population spread
|
||||
|
||||
## Procedural Name Generation
|
||||
|
||||
**File:** `modules/names-generator.js`
|
||||
**Algorithm:** Markov Chains
|
||||
|
||||
```javascript
|
||||
Names.generate(base, type) {
|
||||
const chain = nameBases[base];
|
||||
const name = markovGenerate(chain, type);
|
||||
return name;
|
||||
}
|
||||
```
|
||||
|
||||
**Name Bases:**
|
||||
Each culture has a name base (e.g., "English", "Arabic", "Chinese") used to generate:
|
||||
- Burg names (e.g., "Oakshire", "Riverton")
|
||||
- Province names
|
||||
- Character names
|
||||
- Geographic feature names
|
||||
|
||||
**Markov Chains:**
|
||||
- Learns patterns from example names
|
||||
- Generates new names matching the style
|
||||
- Produces authentic-sounding results
|
||||
|
||||
## Randomization & Seeds
|
||||
|
||||
**Seed Format:**
|
||||
- Short alphanumeric string
|
||||
- Example: "abc123"
|
||||
|
||||
**Determinism:**
|
||||
- Same seed = identical map
|
||||
- Allows sharing maps by seed
|
||||
- Useful for debugging
|
||||
|
||||
**Randomization:**
|
||||
Uses custom PRNG (Alea) for:
|
||||
- Cross-platform consistency
|
||||
- Save/load reliability
|
||||
- Reproducible generation
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Generation Speed
|
||||
|
||||
**Fast Operations:**
|
||||
- Grid generation (~100ms)
|
||||
- Heightmap (~200ms)
|
||||
- Climate (~50ms)
|
||||
|
||||
**Slow Operations:**
|
||||
- River generation (~500ms+)
|
||||
- Culture expansion (~300ms)
|
||||
- State generation (~400ms)
|
||||
|
||||
**Total Time:** ~2-5 seconds for full map
|
||||
|
||||
### Optimization Techniques
|
||||
|
||||
1. **Typed Arrays** - Memory-efficient storage
|
||||
2. **Minimal Reflows** - Batch DOM updates
|
||||
3. **Incremental Rendering** - Progressive display
|
||||
4. **Spatial Indexing** - Fast neighbor lookups
|
||||
5. **Caching** - Reuse calculated values
|
||||
|
||||
## Troubleshooting Generation Issues
|
||||
|
||||
### Common Problems
|
||||
|
||||
**No Rivers Generating:**
|
||||
- Check precipitation settings
|
||||
- Ensure adequate elevation gradients
|
||||
- Verify template allows rivers
|
||||
|
||||
**States Not Forming:**
|
||||
- Increase culture count
|
||||
- Check biome habitability
|
||||
- Ensure enough land area
|
||||
|
||||
**Performance Issues:**
|
||||
- Reduce cell count
|
||||
- Simplify heightmap
|
||||
- Disable unused features
|
||||
|
||||
For more help, see [Performance Tips](https://github.com/Azgaar/Fantasy-Map-Generator/wiki/Tips#performance-tips).
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Data Model](Data-Model.md) - Understanding the data structures
|
||||
- [Modules Reference](Modules-Reference.md) - Detailed module documentation
|
||||
- [Architecture](Architecture.md) - System design overview
|
||||
780
wiki/Getting-Started.md
Normal file
780
wiki/Getting-Started.md
Normal file
|
|
@ -0,0 +1,780 @@
|
|||
# Getting Started
|
||||
|
||||
Welcome! This guide will help you get started with the Fantasy Map Generator, whether you're a user wanting to create maps or a developer wanting to contribute.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [For Users](#for-users)
|
||||
2. [For Developers](#for-developers)
|
||||
3. [Quick Start Tutorial](#quick-start-tutorial)
|
||||
4. [Contributing](#contributing)
|
||||
5. [Resources](#resources)
|
||||
|
||||
---
|
||||
|
||||
## For Users
|
||||
|
||||
### Using the Online Version
|
||||
|
||||
The easiest way to use the Fantasy Map Generator is through the web application:
|
||||
|
||||
**Link:** [azgaar.github.io/Fantasy-Map-Generator](https://azgaar.github.io/Fantasy-Map-Generator)
|
||||
|
||||
**Requirements:**
|
||||
- Modern web browser (Chrome, Firefox, Safari, or Edge)
|
||||
- JavaScript enabled
|
||||
- Recommended: Desktop or laptop (mobile works but with limitations)
|
||||
|
||||
**No installation needed!** Just open the link and start generating maps.
|
||||
|
||||
---
|
||||
|
||||
### Using the Desktop Version
|
||||
|
||||
For offline use or better performance, download the Electron desktop application:
|
||||
|
||||
**Download:** [GitHub Releases](https://github.com/Azgaar/Fantasy-Map-Generator/releases)
|
||||
|
||||
**Installation:**
|
||||
|
||||
1. Go to the releases page
|
||||
2. Download the archive for your platform:
|
||||
- **Windows**: `FMG-windows-x64.zip`
|
||||
- **macOS**: `FMG-darwin-x64.zip`
|
||||
- **Linux**: `FMG-linux-x64.zip`
|
||||
3. Extract the archive
|
||||
4. Run the executable:
|
||||
- **Windows**: `FMG.exe`
|
||||
- **macOS**: `FMG.app`
|
||||
- **Linux**: `FMG`
|
||||
|
||||
**Benefits:**
|
||||
- Works offline
|
||||
- Better performance
|
||||
- No browser limitations
|
||||
- Easier file management
|
||||
|
||||
---
|
||||
|
||||
### Creating Your First Map
|
||||
|
||||
**Step 1: Open the Generator**
|
||||
|
||||
Visit the website or open the desktop app.
|
||||
|
||||
**Step 2: Generate**
|
||||
|
||||
Click the **"Generate New Map"** button (or it generates automatically on first load).
|
||||
|
||||
**Step 3: Explore**
|
||||
|
||||
Your map is ready! You'll see:
|
||||
- Terrain with mountains, plains, and water
|
||||
- Rivers and lakes
|
||||
- Political boundaries (states)
|
||||
- Cities and towns
|
||||
- Labels and names
|
||||
|
||||
**Step 4: Customize**
|
||||
|
||||
Use the toolbar to:
|
||||
- Toggle layers on/off
|
||||
- Zoom and pan
|
||||
- Open editors to modify the map
|
||||
- Change visual style
|
||||
|
||||
**Step 5: Save**
|
||||
|
||||
Click **File → Save Map** to download your map as a `.map` file.
|
||||
|
||||
**Congratulations!** You've created your first fantasy map.
|
||||
|
||||
---
|
||||
|
||||
### Basic Controls
|
||||
|
||||
**Mouse Controls:**
|
||||
- **Left Click**: Select elements
|
||||
- **Right Click**: Context menu (in editors)
|
||||
- **Drag**: Pan the map
|
||||
- **Scroll**: Zoom in/out
|
||||
- **Hover**: Show tooltips
|
||||
|
||||
**Keyboard Shortcuts:**
|
||||
- **Ctrl+Z**: Undo
|
||||
- **Ctrl+Y**: Redo
|
||||
- **Ctrl+S**: Save
|
||||
- **Ctrl+O**: Open
|
||||
- **F11**: Fullscreen
|
||||
- **Space**: Toggle pan mode
|
||||
|
||||
---
|
||||
|
||||
### Common Tasks
|
||||
|
||||
#### Changing Terrain
|
||||
|
||||
1. Click **Layers → Heightmap**
|
||||
2. Click **Edit Heightmap**
|
||||
3. Use brush tools to raise/lower terrain
|
||||
4. Click **Apply**
|
||||
|
||||
#### Adding a City
|
||||
|
||||
1. Click **Layers → Burgs**
|
||||
2. Click **Add Burg**
|
||||
3. Click on map where you want the city
|
||||
4. Fill in name and details
|
||||
5. Click **Add**
|
||||
|
||||
#### Customizing Colors
|
||||
|
||||
1. Click **Style → Edit Style**
|
||||
2. Select element to customize (states, terrain, etc.)
|
||||
3. Choose colors
|
||||
4. Click **Apply**
|
||||
|
||||
#### Exporting
|
||||
|
||||
1. Click **File → Export**
|
||||
2. Choose format (SVG, PNG, etc.)
|
||||
3. Configure options
|
||||
4. Click **Export**
|
||||
|
||||
---
|
||||
|
||||
### Learning Resources
|
||||
|
||||
**Official Resources:**
|
||||
- [Wiki](https://github.com/Azgaar/Fantasy-Map-Generator/wiki) - Comprehensive guides
|
||||
- [YouTube Channel](https://www.youtube.com/channel/UCb0_JfUg6t2k_dYuLBrGg_g) - Video tutorials
|
||||
- [Blog](https://azgaar.wordpress.com) - Articles and tips
|
||||
|
||||
**Community:**
|
||||
- [Discord](https://discordapp.com/invite/X7E84HU) - Live chat and support
|
||||
- [Reddit](https://www.reddit.com/r/FantasyMapGenerator) - Share maps and discuss
|
||||
|
||||
**Examples:**
|
||||
- [Gallery](https://www.reddit.com/r/FantasyMapGenerator/search?q=flair%3AShowcase&restrict_sr=1) - Community maps for inspiration
|
||||
|
||||
---
|
||||
|
||||
## For Developers
|
||||
|
||||
### Setting Up Development Environment
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- **Git** - Version control
|
||||
- **Modern Browser** - Chrome/Firefox with DevTools
|
||||
- **Text Editor** - VS Code, Sublime, Atom, etc.
|
||||
- **Optional**: Node.js (for local server)
|
||||
|
||||
#### Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Azgaar/Fantasy-Map-Generator.git
|
||||
cd Fantasy-Map-Generator
|
||||
```
|
||||
|
||||
#### Run Locally
|
||||
|
||||
**Option 1: Python Server**
|
||||
|
||||
```bash
|
||||
# Python 3
|
||||
python -m http.server 8080
|
||||
|
||||
# Python 2
|
||||
python -m SimpleHTTPServer 8080
|
||||
```
|
||||
|
||||
**Option 2: Node.js Server**
|
||||
|
||||
```bash
|
||||
npx http-server -p 8080
|
||||
```
|
||||
|
||||
**Option 3: VS Code Live Server**
|
||||
|
||||
1. Install "Live Server" extension
|
||||
2. Right-click `index.html`
|
||||
3. Select "Open with Live Server"
|
||||
|
||||
**Option 4: Direct File Access**
|
||||
|
||||
Open `index.html` directly in browser (some features may not work due to CORS).
|
||||
|
||||
#### Access the Application
|
||||
|
||||
Open your browser and navigate to:
|
||||
```
|
||||
http://localhost:8080
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
Fantasy-Map-Generator/
|
||||
├── index.html # Main HTML file
|
||||
├── index.css # Main stylesheet
|
||||
├── main.js # Core application logic
|
||||
├── versioning.js # Map version migration
|
||||
├── modules/ # Feature modules
|
||||
│ ├── heightmap-generator.js
|
||||
│ ├── river-generator.js
|
||||
│ ├── cultures-generator.js
|
||||
│ ├── burgs-and-states.js
|
||||
│ ├── religions-generator.js
|
||||
│ ├── routes-generator.js
|
||||
│ ├── military-generator.js
|
||||
│ ├── markers-generator.js
|
||||
│ ├── names-generator.js
|
||||
│ ├── coa-generator.js
|
||||
│ ├── coa-renderer.js
|
||||
│ ├── biomes.js
|
||||
│ ├── lakes.js
|
||||
│ ├── voronoi.js
|
||||
│ ├── fonts.js
|
||||
│ ├── relief-icons.js
|
||||
│ ├── ocean-layers.js
|
||||
│ ├── io/ # Save/load/export
|
||||
│ ├── ui/ # 41+ editor dialogs
|
||||
│ ├── renderers/ # Visualization
|
||||
│ └── dynamic/ # On-demand utilities
|
||||
├── libs/ # Third-party libraries
|
||||
│ ├── d3.min.js
|
||||
│ ├── delaunator.min.js
|
||||
│ ├── jquery.min.js
|
||||
│ └── jquery-ui.min.js
|
||||
├── utils/ # Utility functions
|
||||
├── config/ # Configuration files
|
||||
├── styles/ # Additional stylesheets
|
||||
├── images/ # Image assets
|
||||
├── charges/ # Heraldic charges (200+)
|
||||
└── heightmaps/ # Template heightmaps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Making Your First Change
|
||||
|
||||
#### Example: Changing Default Sea Level
|
||||
|
||||
**File:** `modules/heightmap-generator.js`
|
||||
|
||||
**Find:**
|
||||
```javascript
|
||||
const seaLevel = 20; // Default sea level
|
||||
```
|
||||
|
||||
**Change to:**
|
||||
```javascript
|
||||
const seaLevel = 25; // Raised sea level
|
||||
```
|
||||
|
||||
**Save and reload** - Sea level is now higher.
|
||||
|
||||
---
|
||||
|
||||
### Development Workflow
|
||||
|
||||
#### 1. Create a Branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature/my-feature
|
||||
```
|
||||
|
||||
#### 2. Make Changes
|
||||
|
||||
Edit files in your preferred editor.
|
||||
|
||||
#### 3. Test Changes
|
||||
|
||||
- Reload the browser
|
||||
- Test affected features
|
||||
- Check browser console for errors
|
||||
|
||||
#### 4. Commit Changes
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add description of changes"
|
||||
```
|
||||
|
||||
#### 5. Push Branch
|
||||
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
#### 6. Create Pull Request
|
||||
|
||||
1. Go to GitHub repository
|
||||
2. Click "Pull Requests"
|
||||
3. Click "New Pull Request"
|
||||
4. Select your branch
|
||||
5. Describe changes
|
||||
6. Submit
|
||||
|
||||
---
|
||||
|
||||
### Code Style Guidelines
|
||||
|
||||
#### JavaScript Style
|
||||
|
||||
**Use strict mode:**
|
||||
```javascript
|
||||
"use strict";
|
||||
```
|
||||
|
||||
**Module pattern:**
|
||||
```javascript
|
||||
window.MyModule = (function() {
|
||||
// Private
|
||||
function privateFunction() {}
|
||||
|
||||
// Public
|
||||
function publicFunction() {}
|
||||
|
||||
return { publicFunction };
|
||||
})();
|
||||
```
|
||||
|
||||
**Naming conventions:**
|
||||
- Variables: `camelCase`
|
||||
- Constants: `UPPER_SNAKE_CASE`
|
||||
- Functions: `camelCase`
|
||||
- Modules: `PascalCase`
|
||||
|
||||
**Comments:**
|
||||
```javascript
|
||||
// Single-line for brief explanations
|
||||
|
||||
/* Multi-line for
|
||||
longer explanations */
|
||||
```
|
||||
|
||||
#### Formatting
|
||||
|
||||
- **Indentation**: 2 spaces (no tabs)
|
||||
- **Semicolons**: Use them
|
||||
- **Quotes**: Prefer double quotes
|
||||
- **Line length**: ~100 characters
|
||||
|
||||
#### Best Practices
|
||||
|
||||
1. **No global pollution** - Use modules
|
||||
2. **Use typed arrays** for cell data
|
||||
3. **Cache DOM selections** - Don't query repeatedly
|
||||
4. **Minimize D3 updates** - Batch when possible
|
||||
5. **Comment complex logic** - Help future maintainers
|
||||
|
||||
---
|
||||
|
||||
### Understanding the Codebase
|
||||
|
||||
#### Key Concepts
|
||||
|
||||
**1. Global State**
|
||||
|
||||
```javascript
|
||||
grid // Voronoi diagram + terrain
|
||||
pack // Civilizations + derived data
|
||||
seed // Random seed
|
||||
```
|
||||
|
||||
All modules access these globals.
|
||||
|
||||
**2. Generation Pipeline**
|
||||
|
||||
```javascript
|
||||
generateGrid()
|
||||
→ generateHeightmap()
|
||||
→ markFeatures()
|
||||
→ calculateClimate()
|
||||
→ generateRivers()
|
||||
→ defineBiomes()
|
||||
→ generateCultures()
|
||||
→ generateStates()
|
||||
→ render()
|
||||
```
|
||||
|
||||
Each step builds on the previous.
|
||||
|
||||
**3. Data Structures**
|
||||
|
||||
Heavily uses typed arrays:
|
||||
```javascript
|
||||
pack.cells.h = new Uint8Array(n); // Heights
|
||||
pack.cells.s = new Uint16Array(n); // State IDs
|
||||
```
|
||||
|
||||
See [Data Model](Data-Model.md) for details.
|
||||
|
||||
**4. Rendering**
|
||||
|
||||
Uses D3.js for SVG manipulation:
|
||||
```javascript
|
||||
d3.select('#states').selectAll('path')
|
||||
.data(pack.states)
|
||||
.enter().append('path')
|
||||
.attr('d', drawStatePath)
|
||||
.attr('fill', d => d.color);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
#### Browser DevTools
|
||||
|
||||
**Console:**
|
||||
- View errors and warnings
|
||||
- Log values: `console.log(grid)`
|
||||
- Inspect objects: `console.dir(pack.states[0])`
|
||||
|
||||
**Debugger:**
|
||||
- Set breakpoints in sources
|
||||
- Step through code
|
||||
- Inspect variables
|
||||
|
||||
**Performance:**
|
||||
- Profile generation
|
||||
- Identify slow functions
|
||||
- Monitor memory usage
|
||||
|
||||
#### Common Issues
|
||||
|
||||
**Problem: Changes not appearing**
|
||||
- Hard refresh (Ctrl+Shift+R)
|
||||
- Clear browser cache
|
||||
- Check console for errors
|
||||
|
||||
**Problem: Map not generating**
|
||||
- Check console for errors
|
||||
- Verify module loading order
|
||||
- Test with lower cell count
|
||||
|
||||
**Problem: Performance issues**
|
||||
- Reduce cell count
|
||||
- Profile in DevTools
|
||||
- Check for infinite loops
|
||||
|
||||
---
|
||||
|
||||
### Testing
|
||||
|
||||
Currently, the project lacks automated tests. Manual testing is required:
|
||||
|
||||
#### Test Checklist
|
||||
|
||||
- [ ] Map generates successfully
|
||||
- [ ] All layers render correctly
|
||||
- [ ] Editors open without errors
|
||||
- [ ] Changes persist after save/load
|
||||
- [ ] Export formats work
|
||||
- [ ] No console errors
|
||||
|
||||
#### Test Different Scenarios
|
||||
|
||||
- Different templates
|
||||
- Different cell counts
|
||||
- Edge cases (very high/low values)
|
||||
- Browser compatibility
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Tutorial
|
||||
|
||||
### Tutorial: Adding a Custom Biome
|
||||
|
||||
This tutorial shows how to add a new biome type called "Jungle".
|
||||
|
||||
**Step 1: Define Biome Data**
|
||||
|
||||
Edit `modules/biomes.js`:
|
||||
|
||||
```javascript
|
||||
// Add to biomesData.i array
|
||||
14 // New ID for Jungle
|
||||
|
||||
// Add to biomesData.name array
|
||||
"Jungle"
|
||||
|
||||
// Add to biomesData.color array
|
||||
"#2d5016" // Dark green
|
||||
|
||||
// Add to biomesData.habitability array
|
||||
50 // Medium habitability
|
||||
|
||||
// Add to other arrays...
|
||||
```
|
||||
|
||||
**Step 2: Update Biome Matrix**
|
||||
|
||||
Add logic to assign "Jungle" biome:
|
||||
|
||||
```javascript
|
||||
// In high temp + high precipitation
|
||||
if (temp > 80 && prec > 200) {
|
||||
return 14; // Jungle
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Test**
|
||||
|
||||
1. Reload the application
|
||||
2. Generate a new map
|
||||
3. Look for jungle biomes in hot, wet regions
|
||||
4. Check if rendering works correctly
|
||||
|
||||
**Step 4: Add Icons (Optional)**
|
||||
|
||||
Add jungle-specific relief icons in `modules/relief-icons.js`.
|
||||
|
||||
**Congratulations!** You've added a custom biome.
|
||||
|
||||
---
|
||||
|
||||
### Tutorial: Creating a Simple Editor
|
||||
|
||||
This tutorial shows how to create a basic editor dialog.
|
||||
|
||||
**Step 1: Create Editor File**
|
||||
|
||||
Create `modules/ui/my-editor.js`:
|
||||
|
||||
```javascript
|
||||
"use strict";
|
||||
|
||||
function editMyFeature() {
|
||||
// Create dialog
|
||||
$("#myEditor").dialog({
|
||||
title: "My Feature Editor",
|
||||
width: 400,
|
||||
height: 300,
|
||||
buttons: {
|
||||
Apply: applyChanges,
|
||||
Close: function() { $(this).dialog("close"); }
|
||||
}
|
||||
});
|
||||
|
||||
function applyChanges() {
|
||||
// Implement your logic
|
||||
const value = $("#myInput").val();
|
||||
console.log("Applied:", value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Add HTML Dialog**
|
||||
|
||||
In `index.html`, add:
|
||||
|
||||
```html
|
||||
<div id="myEditor" class="dialog">
|
||||
<label>My Setting:</label>
|
||||
<input id="myInput" type="text" />
|
||||
</div>
|
||||
```
|
||||
|
||||
**Step 3: Include Script**
|
||||
|
||||
In `index.html`, add:
|
||||
|
||||
```html
|
||||
<script src="modules/ui/my-editor.js"></script>
|
||||
```
|
||||
|
||||
**Step 4: Add Menu Item**
|
||||
|
||||
Add button to toolbar or menu to call `editMyFeature()`.
|
||||
|
||||
**Step 5: Test**
|
||||
|
||||
Click the button and verify dialog opens.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
### Ways to Contribute
|
||||
|
||||
1. **Report Bugs** - Use [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues)
|
||||
2. **Suggest Features** - Use [Discussions](https://github.com/Azgaar/Fantasy-Map-Generator/discussions)
|
||||
3. **Improve Documentation** - Submit PR with doc improvements
|
||||
4. **Fix Bugs** - Pick an issue and submit a fix
|
||||
5. **Add Features** - Implement new functionality
|
||||
6. **Share Maps** - Inspire others on [Reddit](https://www.reddit.com/r/FantasyMapGenerator)
|
||||
|
||||
### Contribution Guidelines
|
||||
|
||||
#### Before Contributing
|
||||
|
||||
1. **Read the documentation**
|
||||
- [Data Model](Data-Model.md)
|
||||
- [Architecture](Architecture.md)
|
||||
- [Generation Process](Generation-Process.md)
|
||||
|
||||
2. **Check existing issues**
|
||||
- Avoid duplicates
|
||||
- Discuss major changes first
|
||||
|
||||
3. **Start small**
|
||||
- Begin with minor changes
|
||||
- Get familiar with codebase
|
||||
- Build up to larger features
|
||||
|
||||
#### Pull Request Process
|
||||
|
||||
1. **Fork the repository**
|
||||
2. **Create a branch** (`feature/my-feature`)
|
||||
3. **Make changes** with clear commits
|
||||
4. **Test thoroughly**
|
||||
5. **Update documentation** if needed
|
||||
6. **Submit pull request** with clear description
|
||||
7. **Respond to feedback**
|
||||
|
||||
#### Code Review
|
||||
|
||||
Maintainers will review your PR and may:
|
||||
- Request changes
|
||||
- Suggest improvements
|
||||
- Merge if approved
|
||||
|
||||
Be patient and receptive to feedback!
|
||||
|
||||
---
|
||||
|
||||
### Community Guidelines
|
||||
|
||||
**Be respectful:**
|
||||
- Kind and constructive communication
|
||||
- Welcome newcomers
|
||||
- Help others learn
|
||||
|
||||
**Stay on topic:**
|
||||
- Keep discussions relevant
|
||||
- Use appropriate channels
|
||||
|
||||
**Share knowledge:**
|
||||
- Document your solutions
|
||||
- Help others with issues
|
||||
- Create tutorials
|
||||
|
||||
**Follow the Code of Conduct:**
|
||||
See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Documentation
|
||||
|
||||
- **[Home](Home.md)** - Wiki home
|
||||
- **[Architecture](Architecture.md)** - System design
|
||||
- **[Data Model](Data-Model.md)** - Data structures
|
||||
- **[Generation Process](Generation-Process.md)** - How maps are created
|
||||
- **[Modules Reference](Modules-Reference.md)** - Module documentation
|
||||
- **[Features and UI](Features-and-UI.md)** - Feature guide
|
||||
|
||||
### External Resources
|
||||
|
||||
**Inspiration:**
|
||||
- [Generating Fantasy Maps](https://mewo2.com/notes/terrain) - Martin O'Leary
|
||||
- [Polygonal Map Generation](http://www-cs-students.stanford.edu/~amitp/game-programming/polygon-map-generation) - Amit Patel
|
||||
- [Here Dragons Abound](https://heredragonsabound.blogspot.com) - Scott Turner
|
||||
|
||||
**Tools:**
|
||||
- [D3.js Documentation](https://d3js.org/)
|
||||
- [SVG Reference](https://developer.mozilla.org/en-US/docs/Web/SVG)
|
||||
- [Delaunator](https://github.com/mapbox/delaunator)
|
||||
|
||||
### Getting Help
|
||||
|
||||
**Questions?**
|
||||
- Ask on [Discord](https://discordapp.com/invite/X7E84HU)
|
||||
- Post on [Reddit](https://www.reddit.com/r/FantasyMapGenerator)
|
||||
- Search [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues)
|
||||
|
||||
**Bug Reports?**
|
||||
- Use [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues)
|
||||
- Include steps to reproduce
|
||||
- Provide browser/version info
|
||||
- Share console errors
|
||||
|
||||
**Feature Requests?**
|
||||
- Use [Discussions](https://github.com/Azgaar/Fantasy-Map-Generator/discussions)
|
||||
- Describe use case
|
||||
- Explain expected behavior
|
||||
|
||||
**Private Inquiries?**
|
||||
- Email: azgaar.fmg@yandex.by
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Users
|
||||
|
||||
1. **Experiment** - Try different templates and options
|
||||
2. **Explore editors** - Customize every aspect
|
||||
3. **Share your maps** - Post to community
|
||||
4. **Learn advanced features** - 3D view, submaps, etc.
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Read the codebase** - Explore key modules
|
||||
2. **Make small changes** - Build confidence
|
||||
3. **Fix a bug** - Pick from issues
|
||||
4. **Add a feature** - Implement something new
|
||||
5. **Improve docs** - Help others learn
|
||||
|
||||
---
|
||||
|
||||
## Welcome to the Community!
|
||||
|
||||
Whether you're creating maps for your D&D campaign, writing a fantasy novel, or contributing code, we're glad you're here!
|
||||
|
||||
**Happy mapping!** 🗺️
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Is it really free?**
|
||||
A: Yes! Completely free and open source.
|
||||
|
||||
**Q: Can I use maps commercially?**
|
||||
A: Yes! The MIT license allows commercial use.
|
||||
|
||||
**Q: Do I need to credit the generator?**
|
||||
A: Not required, but appreciated!
|
||||
|
||||
**Q: Can I run it offline?**
|
||||
A: Yes, use the desktop version or host locally.
|
||||
|
||||
**Q: How do I report bugs?**
|
||||
A: Use [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues).
|
||||
|
||||
**Q: Can I contribute if I'm new to coding?**
|
||||
A: Absolutely! Start with documentation or small bug fixes.
|
||||
|
||||
**Q: Where can I see examples?**
|
||||
A: Check the [Reddit community](https://www.reddit.com/r/FantasyMapGenerator) for amazing maps!
|
||||
|
||||
**Q: Is there a mobile app?**
|
||||
A: Not currently, but the web version works on mobile browsers.
|
||||
|
||||
**Q: Can I import my own data?**
|
||||
A: Yes, see export/import features for JSON data.
|
||||
|
||||
**Q: How can I support the project?**
|
||||
A: [Patreon](https://www.patreon.com/azgaar) or contribute code!
|
||||
|
||||
---
|
||||
|
||||
For more questions, visit the community channels!
|
||||
105
wiki/Home.md
Normal file
105
wiki/Home.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
# Fantasy Map Generator Wiki
|
||||
|
||||
Welcome to the Fantasy Map Generator documentation! This wiki provides comprehensive information about how the generator works, its architecture, and how to use and contribute to the project.
|
||||
|
||||
## What is Fantasy Map Generator?
|
||||
|
||||
Azgaar's Fantasy Map Generator is a free web application that helps fantasy writers, game masters, and cartographers create and edit fantasy maps. It uses procedural generation to create realistic-looking maps with terrain, water features, climates, civilizations, and much more.
|
||||
|
||||
**Live Application:** [azgaar.github.io/Fantasy-Map-Generator](https://azgaar.github.io/Fantasy-Map-Generator)
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Procedural Terrain Generation** - Realistic heightmaps, mountains, hills, and valleys
|
||||
- **Water Simulation** - Rivers flow naturally based on elevation, lakes form in depressions
|
||||
- **Climate System** - Temperature and precipitation affect biome distribution
|
||||
- **Civilization Generation** - Cultures, states, religions, towns, and political boundaries
|
||||
- **Extensive Customization** - 41+ specialized editors for every aspect of the map
|
||||
- **Export Options** - Save/load maps, export to various formats
|
||||
- **Procedural Naming** - Realistic place names using Markov chains
|
||||
- **Coat of Arms** - Procedurally generated heraldry for states
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
This wiki is organized into the following sections:
|
||||
|
||||
### Core Concepts
|
||||
|
||||
- **[Architecture](Architecture.md)** - High-level system architecture and design patterns
|
||||
- **[Data Model](Data-Model.md)** - Data structures, objects, and relationships
|
||||
- **[Generation Process](Generation-Process.md)** - How maps are generated step-by-step
|
||||
|
||||
### Reference Documentation
|
||||
|
||||
- **[Modules Reference](Modules-Reference.md)** - Detailed documentation of all modules
|
||||
- **[Features and UI](Features-and-UI.md)** - Complete feature list and UI capabilities
|
||||
- **[Getting Started](Getting-Started.md)** - Quick start guide for developers
|
||||
|
||||
### Additional Resources
|
||||
|
||||
- **[GitHub Repository](https://github.com/Azgaar/Fantasy-Map-Generator)** - Source code
|
||||
- **[Discord Community](https://discordapp.com/invite/X7E84HU)** - Join the community
|
||||
- **[Reddit Community](https://www.reddit.com/r/FantasyMapGenerator)** - Share your maps
|
||||
- **[Trello Board](https://trello.com/b/7x832DG4/fantasy-map-generator)** - Development progress
|
||||
- **[Patreon](https://www.patreon.com/azgaar)** - Support the project
|
||||
|
||||
## Quick Overview
|
||||
|
||||
### How It Works
|
||||
|
||||
The generator creates maps through a multi-stage process:
|
||||
|
||||
1. **Grid Generation** - Creates a Voronoi diagram from jittered points
|
||||
2. **Terrain Creation** - Generates heightmap using templates or images
|
||||
3. **Climate Simulation** - Calculates temperature and precipitation
|
||||
4. **Water Features** - Generates rivers and lakes based on elevation
|
||||
5. **Biomes** - Assigns vegetation types based on climate
|
||||
6. **Civilization** - Places cultures, states, and settlements
|
||||
7. **Infrastructure** - Creates roads and trade routes
|
||||
8. **Rendering** - Draws all elements to an SVG canvas
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Pure JavaScript** - No build system required
|
||||
- **D3.js** - Data visualization and SVG manipulation
|
||||
- **Delaunator** - Fast Delaunay triangulation
|
||||
- **jQuery/jQuery UI** - UI components and interactions
|
||||
- **SVG** - Vector graphics rendering
|
||||
- **Typed Arrays** - Efficient data storage
|
||||
|
||||
### Data Model Overview
|
||||
|
||||
The generator maintains two main data structures:
|
||||
|
||||
- **`grid`** - Initial Voronoi graph (~10,000 cells) with terrain and climate data
|
||||
- **`pack`** - Packed graph with civilizations, settlements, and derived features
|
||||
|
||||
All map data is stored in these objects, enabling save/load functionality and full editability.
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull requests are highly welcomed! Before contributing:
|
||||
|
||||
1. Read the [Data Model](Data-Model.md) documentation
|
||||
2. Review the [Architecture](Architecture.md) guide
|
||||
3. Start with minor changes to familiarize yourself with the codebase
|
||||
4. Check existing [issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues) and [discussions](https://github.com/Azgaar/Fantasy-Map-Generator/discussions)
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Bug Reports** - Use [GitHub Issues](https://github.com/Azgaar/Fantasy-Map-Generator/issues) or Discord #bugs channel
|
||||
- **Questions** - Ask on [Discord](https://discordapp.com/invite/X7E84HU) or [Reddit](https://www.reddit.com/r/FantasyMapGenerator)
|
||||
- **Performance Issues** - See [Performance Tips](https://github.com/Azgaar/Fantasy-Map-Generator/wiki/Tips#performance-tips)
|
||||
- **Private Inquiries** - Email: azgaar.fmg@yandex.by
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
This project was inspired by:
|
||||
|
||||
- Martin O'Leary's [Generating fantasy maps](https://mewo2.com/notes/terrain)
|
||||
- Amit Patel's [Polygonal Map Generation for Games](http://www-cs-students.stanford.edu/~amitp/game-programming/polygon-map-generation)
|
||||
- Scott Turner's [Here Dragons Abound](https://heredragonsabound.blogspot.com)
|
||||
880
wiki/Modules-Reference.md
Normal file
880
wiki/Modules-Reference.md
Normal file
|
|
@ -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
|
||||
144
wiki/README.md
Normal file
144
wiki/README.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
# Fantasy Map Generator Wiki Documentation
|
||||
|
||||
This directory contains comprehensive documentation for the Fantasy Map Generator project.
|
||||
|
||||
## Documentation Overview
|
||||
|
||||
The wiki is organized into the following main sections:
|
||||
|
||||
### Core Documentation
|
||||
|
||||
1. **[Home](Home.md)** - Wiki homepage with overview and quick links
|
||||
2. **[Getting Started](Getting-Started.md)** - Beginner's guide for users and developers
|
||||
3. **[Architecture](Architecture.md)** - System architecture and design patterns
|
||||
4. **[Data Model](Data-Model.md)** - Complete data structures and relationships
|
||||
5. **[Generation Process](Generation-Process.md)** - Detailed map generation pipeline
|
||||
6. **[Modules Reference](Modules-Reference.md)** - Documentation for all modules
|
||||
7. **[Features and UI](Features-and-UI.md)** - Complete feature list and UI guide
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### For Users
|
||||
- New to the generator? Start with [Getting Started](Getting-Started.md)
|
||||
- Want to learn all features? See [Features and UI](Features-and-UI.md)
|
||||
- Need help with something? Check [Home](Home.md) for support links
|
||||
|
||||
### For Developers
|
||||
- Setting up development? See [Getting Started](Getting-Started.md#for-developers)
|
||||
- Understanding the architecture? Read [Architecture](Architecture.md)
|
||||
- Working with data? Check [Data Model](Data-Model.md)
|
||||
- Adding features? Review [Modules Reference](Modules-Reference.md)
|
||||
- Understanding generation? See [Generation Process](Generation-Process.md)
|
||||
|
||||
## What's Documented
|
||||
|
||||
### Architecture Documentation
|
||||
- System design and components
|
||||
- Module organization and patterns
|
||||
- Technology stack
|
||||
- Performance considerations
|
||||
- SVG layer structure
|
||||
- Data flow architecture
|
||||
|
||||
### Data Model Documentation
|
||||
- Grid and Pack data structures
|
||||
- Cell properties and relationships
|
||||
- Civilization hierarchies
|
||||
- Biome data
|
||||
- Data access patterns
|
||||
- Serialization format
|
||||
- Performance considerations
|
||||
|
||||
### Generation Process Documentation
|
||||
- Complete 17-stage generation pipeline
|
||||
- Detailed explanations of each stage
|
||||
- Algorithms and techniques
|
||||
- Climate simulation
|
||||
- Water feature generation
|
||||
- Civilization creation
|
||||
- Procedural name generation
|
||||
|
||||
### Modules Reference
|
||||
- All core generator modules
|
||||
- Civilization generators
|
||||
- Utility modules
|
||||
- Renderers
|
||||
- I/O modules
|
||||
- UI editors (41+)
|
||||
- Module APIs and usage
|
||||
|
||||
### Features Documentation
|
||||
- All user-facing features
|
||||
- Complete UI guide
|
||||
- Editing capabilities
|
||||
- Export and save options
|
||||
- Advanced features
|
||||
- Keyboard shortcuts
|
||||
- Tips and troubleshooting
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
```
|
||||
wiki/
|
||||
├── README.md # This file
|
||||
├── Home.md # Wiki homepage
|
||||
├── Getting-Started.md # Beginner's guide
|
||||
├── Architecture.md # System architecture
|
||||
├── Data-Model.md # Data structures
|
||||
├── Generation-Process.md # Generation pipeline
|
||||
├── Modules-Reference.md # Module documentation
|
||||
└── Features-and-UI.md # Features and UI guide
|
||||
```
|
||||
|
||||
## Contributing to Documentation
|
||||
|
||||
Found an error or want to improve the docs?
|
||||
|
||||
1. Documentation is stored in the `wiki/` directory
|
||||
2. All files are in Markdown format
|
||||
3. Submit pull requests with improvements
|
||||
4. Follow the existing structure and style
|
||||
|
||||
### Documentation Guidelines
|
||||
|
||||
- **Be clear and concise** - Help readers understand quickly
|
||||
- **Use examples** - Show code snippets and usage
|
||||
- **Add diagrams** - Visual aids help comprehension
|
||||
- **Link related topics** - Help readers navigate
|
||||
- **Keep it updated** - Update docs when code changes
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Official Links
|
||||
- **Live Application**: [azgaar.github.io/Fantasy-Map-Generator](https://azgaar.github.io/Fantasy-Map-Generator)
|
||||
- **GitHub Repository**: [github.com/Azgaar/Fantasy-Map-Generator](https://github.com/Azgaar/Fantasy-Map-Generator)
|
||||
- **Discord Community**: [discord.com/invite/X7E84HU](https://discordapp.com/invite/X7E84HU)
|
||||
- **Reddit Community**: [reddit.com/r/FantasyMapGenerator](https://www.reddit.com/r/FantasyMapGenerator)
|
||||
|
||||
### External Documentation
|
||||
- [Official Wiki](https://github.com/Azgaar/Fantasy-Map-Generator/wiki) - Additional guides
|
||||
- [Azgaar's Blog](https://azgaar.wordpress.com) - Development blog
|
||||
- [Trello Board](https://trello.com/b/7x832DG4/fantasy-map-generator) - Development roadmap
|
||||
|
||||
## Version Information
|
||||
|
||||
This documentation is current as of:
|
||||
- **Generator Version**: Latest (continuously updated)
|
||||
- **Documentation Date**: November 2025
|
||||
- **Status**: Comprehensive initial version
|
||||
|
||||
## Feedback
|
||||
|
||||
Have suggestions for improving this documentation?
|
||||
|
||||
- Open an issue on [GitHub](https://github.com/Azgaar/Fantasy-Map-Generator/issues)
|
||||
- Discuss on [Discord](https://discordapp.com/invite/X7E84HU)
|
||||
- Submit a pull request with improvements
|
||||
|
||||
## License
|
||||
|
||||
This documentation is part of the Fantasy Map Generator project and is licensed under the MIT License.
|
||||
|
||||
---
|
||||
|
||||
**Happy mapping!** 🗺️
|
||||
Loading…
Add table
Add a link
Reference in a new issue