mirror of
https://github.com/Azgaar/Fantasy-Map-Generator.git
synced 2025-12-16 17:31:24 +01:00
Add comprehensive wiki documentation
Created extensive wiki documentation covering all aspects of the Fantasy Map Generator: - Home.md: Wiki homepage with overview and navigation - Getting-Started.md: Complete beginner's guide for users and developers - Architecture.md: System architecture, design patterns, and technology stack - Data-Model.md: Detailed data structures and relationships - Generation-Process.md: Step-by-step map generation pipeline - Modules-Reference.md: Documentation for all 20+ modules - Features-and-UI.md: Complete feature list and UI guide - README.md: Wiki directory overview The documentation includes: - High-level architecture and design patterns - Detailed data structures with typed arrays - 17-stage generation pipeline with algorithms - All core modules (generators, renderers, UI, I/O) - 41+ UI editors and features - Code examples and usage patterns - Developer setup and contribution guidelines - User tutorials and quick start guides This wiki provides comprehensive documentation for both users wanting to create maps and developers wanting to understand or contribute to the codebase.
This commit is contained in:
Claude
parent
dede314c94
commit
779e3d03b3
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