Fantasy-Map-Generator/CLAUDE.md

CLAUDE.md - AI Assistant Guide for Fantasy Map Generator

Project Overview

Fantasy Map Generator (FMG) is a free web-based application for creating and editing fantasy maps. It's a massive client-side JavaScript application designed for fantasy writers, game masters, and cartographers.

• Repository: https://github.com/Azgaar/Fantasy-Map-Generator
• Live App: https://azgaar.github.io/Fantasy-Map-Generator
• Language: Pure JavaScript (ES6+)
• License: MIT
• Primary Author: Azgaar (azgaar.fmg@yandex.com)

Architecture & Technology Stack

Core Technologies

• Pure JavaScript (ES6+): NO build system, transpilation, or bundling
• D3.js v7: SVG manipulation, data visualization, zoom/pan interactions
• jQuery 3.1.1 + jQuery UI: DOM manipulation, dialogs, UI components
• Progressive Web App (PWA): Service worker caching, offline support, IndexedDB storage

Key Libraries (/libs/)

d3.min.js              # Main visualization library
delaunator.min.js      # Delaunay triangulation for Voronoi mesh
alea.min.js            # Seedable random number generator
three.min.js           # 3D rendering support
jszip.min.js           # ZIP file creation for exports
polylabel.min.js       # Label placement optimization
tinymce/               # Rich text editor for notes

Architecture Pattern

Global Object Pattern: No module bundler, everything attached to window object:

// Global data structures (from main.js:151-158)
let grid = {};           // Initial Voronoi graph
let pack = {};           // Main packed data structure
let seed;                // Map generation seed
let mapId;               // Unique map identifier
let mapHistory = [];     // Undo/redo history
let modules = {};        // Module initialization flags
let notes = [];          // User notes

Directory Structure

Fantasy-Map-Generator/
├── index.html           # 8,184-line monolithic HTML (entire UI)
├── main.js              # 1,288 lines - initialization, globals, SVG setup
├── versioning.js        # Version management (currently v1.108.11)
├── sw.js                # Service worker for PWA caching
│
├── modules/             # Core application logic (232 JS files)
│   ├── dynamic/         # Dynamically imported modules
│   │   ├── editors/     # Advanced editors (states, religions, cultures)
│   │   ├── overview/    # Data visualization tools
│   │   └── *.js         # Auto-update, installation, hierarchy-tree
│   ├── io/              # Input/Output operations
│   │   ├── cloud.js     # Cloud storage (Dropbox)
│   │   ├── export.js    # Map export functionality
│   │   ├── load.js      # Map loading
│   │   └── save.js      # Map saving
│   ├── renderers/       # SVG rendering (12 files)
│   │   ├── draw-borders.js
│   │   ├── draw-heightmap.js
│   │   ├── draw-markers.js
│   │   └── ...
│   └── ui/              # UI editors and tools (~35 files)
│       ├── editors.js   # Common editor functions
│       ├── options.js   # Map configuration
│       └── ...
│
├── utils/               # Utility functions (15 files)
│   ├── arrayUtils.js
│   ├── colorUtils.js
│   ├── commonUtils.js   # debounce, throttle
│   ├── graphUtils.js    # Graph algorithms (297 lines)
│   ├── pathUtils.js     # SVG path operations (222 lines)
│   └── ...
│
├── charges/             # 400+ SVG heraldic symbols
├── components/          # Reusable UI components
├── config/              # Heightmap template configurations
├── heightmaps/          # Precreated heightmap resources
├── images/              # Application images/icons
├── styles/              # 12 JSON theme presets (default, night, etc.)
│
└── .github/
    ├── pull_request_template.md
    └── ISSUE_TEMPLATE/

Key Files

Entry Points

• index.html (line 1-8184): Entire UI structure, loads all scripts
• main.js (line 1-1288): Initializes globals, SVG layers, data structures
• versioning.js: Current version: 1.108.11 (semantic versioning)

Core Generators

modules/burgs-and-states.js       # City/state generation (1,018 lines)
modules/cultures-generator.js     # Culture system (1,039 lines)
modules/names-generator.js        # Name generation (3,371 lines)
modules/heightmap-generator.js    # Terrain generation (445 lines)
modules/river-generator.js        # River systems (507 lines)
modules/routes-generator.js       # Road/trail generation (537 lines)
modules/religions-generator.js    # Religion system (757 lines)
modules/military-generator.js     # Military units (405 lines)
modules/markers-generator.js      # Map markers (1,163 lines)
modules/coa-generator.js          # Coat of arms logic (1,015 lines)
modules/coa-renderer.js           # COA SVG rendering (2,527 lines)
modules/provinces-generator.js    # Province subdivision (302 lines)
modules/zones-generator.js        # Zone assignment (430 lines)

Data Model

Primary Data Structure: pack Object

The pack object is the heart of FMG's data model. It contains the entire map state using typed arrays for performance:

pack = {
  cells: {
    i: Uint32Array,       // Cell indices
    v: Array,             // Adjacent vertices
    c: Array,             // Adjacent cells
    b: Uint8Array,        // Border flags
    h: Uint8Array,        // Height (0-100)
    temp: Int8Array,      // Temperature
    prec: Uint8Array,     // Precipitation
    f: Uint16Array,       // Feature (biome) ID
    t: Int8Array,         // Terrain type
    haven: Uint16Array,   // Harbor ID
    harbor: Uint8Array,   // Harbor presence
    fl: Uint16Array,      // Flux (river flow)
    r: Uint16Array,       // River ID
    conf: Uint8Array,     // River confluence
    pop: Float32Array,    // Population density
    culture: Uint16Array, // Culture ID
    burg: Uint16Array,    // Settlement ID
    road: Uint16Array,    // Road ID
    route: Uint16Array,   // Route ID
    crossroad: Uint16Array,
    province: Uint16Array,
    state: Uint16Array,   // State ownership
    religion: Uint16Array
  },
  vertices: {
    p: Array,             // Point coordinates [x, y]
    v: Array,             // Adjacent vertices
    c: Array              // Adjacent cells
  },
  features: Array,        // Biome/terrain features
  cultures: Array,        // Culture definitions
  states: Array,          // Political states
  burgs: Array,           // Cities/towns/settlements
  religions: Array,       // Religion definitions
  provinces: Array,       // Province data
  rivers: Array,          // River definitions
  markers: Array,         // Map markers
  notes: Array            // User notes
}

Typed Array Constants

// From main.js:16-20
const INT8_MAX = 127;
const UINT8_MAX = 255;
const UINT16_MAX = 65535;
const UINT32_MAX = 4294967295;

Map Generation Pipeline

Heightmap Generation
  ↓
Voronoi/Delaunay Mesh
  ↓
Biomes & Climate
  ↓
Rivers & Water Features
  ↓
Cultures Assignment
  ↓
States & Capitals
  ↓
Burgs (Cities/Towns)
  ↓
Provinces Subdivision
  ↓
Routes (Roads/Trails)
  ↓
Religions Distribution
  ↓
Military Units
  ↓
Final Rendering

SVG Layer Organization

FMG uses 70+ predefined SVG layer groups in specific render order (from main.js:40-94):

// Background to foreground rendering order
ocean → oceanLayers → oceanPattern → lakes → landmass →
texture → terrs → biomes → cells → rivers → terrain →
regions → borders → routes → temperature → coastline →
ice → population → emblems → labels → icons → armies →
markers → fogging → ruler → debug

Important: When modifying rendering, respect this layer order to avoid z-index issues.

Code Conventions & Style

General Style

1. Strict Mode: Every file starts with "use strict";
2. No Semicolons: Generally omitted (but inconsistent)
3. Naming Conventions:
   • camelCase for variables and functions
   • PascalCase for classes
   • SCREAMING_SNAKE_CASE for constants
4. Comments: Minimal; code is mostly self-documenting
5. String Quotes: Mixed single and double quotes (no standard)

Module Patterns

IIFE (Immediately Invoked Function Expression):

// From burgs-and-states.js:3
window.BurgsAndStates = (() => {
  const generate = () => {
    // Implementation
  };

  return { generate };
})();

// Usage elsewhere:
BurgsAndStates.generate();

Global Function Pattern:

// From draw-borders.js:3
function drawBorders() {
  // Direct global function
}

Utility Module Pattern:

// From utils/commonUtils.js
function debounce(func, ms) { /* ... */ }
function throttle(func, ms) { /* ... */ }
// Directly callable globally

Loading Strategy

index.html loads scripts in three phases:

1. Libraries (D3, jQuery, etc.)
2. Core Modules (synchronous, no defer)
3. UI Modules (with defer attribute)
4. Dynamic Imports (ES6 import() for lazy loading)

Example from index.html:

<!-- Core generators loaded first -->
<script src="modules/names-generator.js?v=1.108.11"></script>
<script src="modules/cultures-generator.js?v=1.108.11"></script>
<script src="modules/burgs-and-states.js?v=1.108.11"></script>
<!-- ... -->
<script src="main.js?v=1.108.11"></script>

<!-- UI modules loaded with defer -->
<script defer src="modules/ui/editors.js?v=1.108.11"></script>
<script defer src="modules/ui/heightmap-editor.js?v=1.108.11"></script>

Debug Flags

// From main.js:5-11
const PRODUCTION = location.hostname &&
                   location.hostname !== "localhost" &&
                   location.hostname !== "127.0.0.1";
const DEBUG = JSON.safeParse(localStorage.getItem("debug")) || {};
const INFO = true;
const TIME = true;   // Performance timing
const WARN = true;
const ERROR = true;

// Usage:
TIME && console.time("placeCapitals");
// ... expensive operation ...
TIME && console.timeEnd("placeCapitals");

Development Workflow

No Build System

• Zero build configuration: No webpack, rollup, or bundlers
• No package.json: No npm dependencies
• No transpilation: No Babel or TypeScript
• Direct file editing: Edit JS → Refresh browser → See changes

Local Development

# Python simple server
python -m http.server 8080

# PHP built-in server
php -S localhost:8080

# Then visit: http://localhost:8080

Versioning Process

Manual 3-step versioning (from pull_request_template.md):

1. Update VERSION in versioning.js:

   const VERSION = "1.108.12"; // Increment using semver
   

2. Update file hashes in index.html for all changed files:

   <script src="modules/burgs-and-states.js?v=1.108.12"></script>
   

3. Update changelog in showUpdateWindow() function (versioning.js) if user-facing

Git Workflow

Commit Message Format (inferred from git log):

<type>(<scope>): <description>

Examples:
fix(v1.108.11): add external icons to export in base64 format
feat(ai-generator): update supported AI models list
refactor: drawReliefIcons, v1.108.4
perf: set text-rendering to optimizeSpeed, v1.108.1
chore: update version to 1.108.8

Types:

• feat: New feature
• fix: Bug fix
• refactor: Code restructuring
• perf: Performance improvement
• chore: Maintenance tasks
• docs: Documentation changes

Scopes: Optional, often includes version number or component name

Pull Request Requirements

From .github/pull_request_template.md:

Required:

• Description of change and motivation
• Type of change (bug fix, feature, refactor, docs, other)
• Version updated in versioning.js
• Changed files hash updated in index.html

Before submitting:

1. Test locally (no automated tests)
2. Check console for errors
3. Verify map generation still works
4. Update version following semver

Common Development Tasks

Adding a New Feature

1. Identify the module type:

   • Generator? → modules/
   • UI Editor? → modules/ui/
   • Renderer? → modules/renderers/
   • Utility? → utils/

2. Create the module file:

   "use strict";
   
   window.MyNewFeature = (() => {
     const generate = () => {
       TIME && console.time("myNewFeature");
       // Implementation
       TIME && console.timeEnd("myNewFeature");
     };
   
     return { generate };
   })();
   

3. Add script tag to index.html:

   <script src="modules/my-new-feature.js?v=1.108.12"></script>
   

4. Update versioning:

   • Increment VERSION in versioning.js
   • Update hash in index.html
   • Add changelog entry if user-facing

Modifying the Data Model

1. Update pack structure in relevant generator
2. Update save/load in modules/io/save.js and modules/io/load.js
3. Test with existing .map files to ensure backward compatibility
4. Update any renderers that use the new data

Adding a New Renderer

1. Create renderer file in modules/renderers/:

   "use strict";
   
   function drawMyFeature() {
     const { cells, myFeatures } = pack;
     const container = svg.select("#myFeatureLayer");
   
     // D3 rendering logic
     container.selectAll("path")
       .data(myFeatures)
       .join("path")
       .attr("d", d => d.path)
       .attr("fill", d => d.color);
   }
   

2. Create SVG layer in main.js:

   let myFeatureLayer = viewbox.append("g")
     .attr("id", "myFeatureLayer");
   

3. Add to render pipeline in appropriate location

Debugging Tips

1. Use DEBUG flags:

   DEBUG && console.log("Debug info:", data);
   TIME && console.time("expensiveOperation");
   

2. Check the debug SVG layer:

   debug.append("circle")
     .attr("cx", x)
     .attr("cy", y)
     .attr("r", 5)
     .attr("fill", "red");
   

3. Use browser DevTools:

   • Network tab: Check script loading
   • Console: Look for TIME logs
   • Sources: Set breakpoints

4. Test map generation:

   • Generate → Verify no console errors
   • Save → Load → Verify data integrity
   • Export → Check output quality

Testing Approach

No formal testing framework:

• No Jest, Mocha, or automated tests
• Manual testing only
• User reports via GitHub issues

Manual testing checklist:

1. Generate new map with default settings
2. Generate with various custom settings
3. Load existing .map files
4. Test all editors (heightmap, states, cultures, etc.)
5. Export in all formats (SVG, PNG, JSON)
6. Check console for errors/warnings
7. Test on multiple browsers (Chrome, Firefox, Safari)

Performance Considerations

Optimization Strategies

1. Typed Arrays: Use for large datasets

   cells.h = new Uint8Array(n);  // Heights 0-255
   cells.pop = new Float32Array(n);  // Population
   

2. D3 Data Binding: Efficient DOM updates

   container.selectAll("path")
     .data(features, d => d.id)  // Key function
     .join("path")  // Efficient enter/update/exit
   

3. Debouncing/Throttling: For frequent events

   const onMouseMove = debounce(handleMouseMove, 100);
   

4. Quadtree for Spatial Queries:

   let burgsTree = d3.quadtree();
   burgsTree.add([x, y]);
   const nearest = burgsTree.find(x, y, radius);
   

5. IndexedDB: For large map storage

   // See libs/indexedDB.js
   

Important Patterns & Anti-Patterns

DO:

✅ Use typed arrays for cell data ✅ Respect SVG layer rendering order ✅ Use TIME flags for performance monitoring ✅ Follow IIFE pattern for new modules ✅ Update version numbers consistently ✅ Test backward compatibility with old .map files ✅ Use D3 data binding for DOM updates ✅ Check for null/undefined before accessing pack data

DON'T:

❌ Add npm dependencies (no build system) ❌ Use ES6 modules (not supported in current architecture) ❌ Modify global data structures directly without updating renderers ❌ Add large libraries (keep bundle size manageable) ❌ Break backward compatibility without migration logic ❌ Add features without updating save/load functionality ❌ Forget to update version hash in index.html ❌ Mix rendering layers (respect z-order)

Common Patterns in Codebase

Random Number Generation

// Use seeded random for reproducibility
const rand = aleaPRNG(seed);
const value = rand();  // 0-1

// Gaussian distribution
const value = gauss(mean, deviation, min, max, rounds);

Cell Iteration

const { cells } = pack;
const n = cells.i.length;

for (let i = 0; i < n; i++) {
  if (cells.h[i] < 20) continue;  // Skip water
  // Process land cells
}

D3 SVG Path Creation

const path = d3.line()
  .x(d => d[0])
  .y(d => d[1])
  .curve(d3.curveBasis);

const pathString = path(points);

Graph Traversal

// BFS example from graphUtils.js
const queue = [startCell];
const visited = new Uint8Array(cells.i.length);

while (queue.length) {
  const cell = queue.shift();
  if (visited[cell]) continue;
  visited[cell] = 1;

  cells.c[cell].forEach(neighbor => {
    if (!visited[neighbor]) queue.push(neighbor);
  });
}

Key Concepts

Voronoi/Delaunay Mesh

FMG uses a Voronoi diagram as the base map structure:

• Cells: Voronoi regions representing map areas
• Vertices: Points where 3+ cells meet
• Edges: Borders between cells
• Delaunay Triangulation: Dual graph for efficient pathfinding

Implementation: Custom Voronoi class in modules/voronoi.js using Delaunator library

Heightmap System

Heights stored as Uint8Array (0-255):

• 0-19: Ocean depths
• 20: Sea level
• 21-99: Land elevations
• 100+: Mountains/peaks (clamped to 255)

Culture & State System

Cultures: Linguistic/ethnic groups with naming patterns States: Political entities with territories, capitals, military

Both use expansion algorithms based on cell scoring and distance from capitals.

Name Generation

Sophisticated system in modules/names-generator.js (3,371 lines):

• Cultural naming patterns
• Procedural phoneme generation
• Linguistic rules for realistic names
• Separate generators for burgs, states, cultures, features

File Modification Guidelines

When Editing index.html

• Line count: 8,184 lines - VERY large file
• Structure: UI components inline (not templated)
• Script tags: Update version hash when modifying JS files
• Dialogs: jQuery UI dialogs defined inline
• Be careful: Easy to break HTML structure

When Editing main.js

• Global scope: Everything here is globally accessible
• SVG layers: Order matters (lines 40-94)
• Constants: Typed array max values defined here
• Initialization: Core setup happens here

When Editing Generators

• Self-contained: Each generator should be independent
• Timing: Wrap in TIME && console.time/timeEnd
• Error handling: Use WARN && console.warn for issues
• Data mutations: Update pack object directly

When Editing Renderers

• Layer awareness: Know which SVG layer you're drawing to
• Clear old content: Remove previous render before redrawing
• D3 data binding: Use .join() for efficient updates
• Performance: Large renders should be optimized

Resources

Documentation

• Project Wiki: https://github.com/Azgaar/Fantasy-Map-Generator/wiki
• Data Model: https://github.com/Azgaar/Fantasy-Map-Generator/wiki/Data-model
• Trello Board: https://trello.com/b/7x832DG4/fantasy-map-generator
• Blog: https://azgaar.wordpress.com

Community

• Discord: https://discordapp.com/invite/X7E84HU
• Reddit: https://www.reddit.com/r/FantasyMapGenerator
• GitHub Issues: https://github.com/Azgaar/Fantasy-Map-Generator/issues

Support

• Patreon: https://www.patreon.com/azgaar
• Email: azgaar.fmg@yandex.com

Troubleshooting Common Issues

Map Won't Generate

1. Check console for errors
2. Verify all scripts loaded (Network tab)
3. Check localStorage isn't corrupted
4. Try clearing browser cache

Save/Load Failures

1. Check IndexedDB quota
2. Verify .map file format (should be valid JSON)
3. Check version compatibility
4. Look for migration errors in console

Performance Issues

1. Reduce number of cells (Options → Map Size)
2. Disable unused layers
3. Use simpler rendering styles
4. Check for memory leaks in console

Rendering Glitches

1. Verify SVG layer order
2. Check for NaN values in coordinates
3. Ensure paths are valid SVG syntax
4. Test in different browsers

Best Practices for AI Assistants

When Analyzing Code

1. Start with the data model: Understand pack structure
2. Check dependencies: See what functions/modules are used
3. Look for patterns: IIFE modules, global functions, D3 usage
4. Trace data flow: How data moves through generation pipeline

When Making Changes

1. Test locally first: No CI/CD, manual testing required
2. Update version properly: Follow 3-step process
3. Maintain backward compatibility: Old .map files should still load
4. Document complex logic: Code is under-commented
5. Check performance: Use TIME flags to measure

When Refactoring

1. Small incremental changes: Large refactors are risky
2. Keep the same API: Don't break existing integrations
3. Test all features: Generator, editors, save/load, export
4. Consider deprecation: Don't remove features abruptly

When Adding Features

1. Check existing code: Similar features might exist
2. Follow existing patterns: IIFE for modules, global for utils
3. Update save/load: Persist new data properly
4. Add UI if needed: Users should access the feature
5. Update documentation: At least in comments/changelog

Quick Reference

File to Edit By Task

Task	Files to Edit
Add new generator	modules/my-generator.js, index.html (script tag)
Modify UI editor	modules/ui/my-editor.js
Change rendering	modules/renderers/draw-my-feature.js
Add utility function	utils/myUtils.js
Update save format	modules/io/save.js, modules/io/load.js
Change map options	modules/ui/options.js, index.html (UI)
Add SVG layer	main.js (lines 40-94), renderer file
Update version	versioning.js, index.html (all script tags)

Common Functions

Function	Location	Purpose
rn(value, decimals)	utils/numberUtils.js	Round number
rand(min, max)	Random utilities	Random in range
gauss(mean, dev, ...)	utils/probabilityUtils.js	Gaussian distribution
debounce(fn, ms)	utils/commonUtils.js	Debounce function
P(probability)	Probability utils	Random boolean
ra(array)	Array utils	Random array element

Common D3 Patterns

// Select SVG layer
const layer = svg.select("#myLayer");

// Data binding
layer.selectAll("path")
  .data(features, d => d.id)
  .join("path")
  .attr("d", d => d.path);

// Zoom/pan
const zoom = d3.zoom()
  .scaleExtent([1, 20])
  .on("zoom", zoomed);

svg.call(zoom);

---

Summary

Fantasy Map Generator is a unique codebase that prioritizes:

1. Accessibility: Runs anywhere without build tools
2. Simplicity: Direct file editing, no complex tooling
3. Performance: Typed arrays, efficient algorithms
4. User experience: Rich UI with extensive customization

When working on FMG, embrace its philosophy: pragmatic simplicity over modern complexity. The lack of build tools is intentional, making it easy for contributors to jump in without setup overhead.

---

Last Updated: 2025-11-14 Current Version: 1.108.11 This guide is for AI assistants working on Fantasy Map Generator codebase.