Fantasy-Map-Generator/wiki/Getting-Started.md

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
2. For Developers
3. Quick Start Tutorial
4. Contributing
5. 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

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

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 - Comprehensive guides
• YouTube Channel - Video tutorials
• Blog - Articles and tips

Community:

• Discord - Live chat and support
• Reddit - Share maps and discuss

Examples:

• Gallery - 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

git clone https://github.com/Azgaar/Fantasy-Map-Generator.git
cd Fantasy-Map-Generator

Run Locally

Option 1: Python Server

# Python 3
python -m http.server 8080

# Python 2
python -m SimpleHTTPServer 8080

Option 2: Node.js Server

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:

const seaLevel = 20; // Default sea level

Change to:

const seaLevel = 25; // Raised sea level

Save and reload - Sea level is now higher.

---

Development Workflow

1. Create a Branch

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

git add .
git commit -m "Add description of changes"

5. Push Branch

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:

"use strict";

Module pattern:

window.MyModule = (function() {
  // Private
  function privateFunction() {}

  // Public
  function publicFunction() {}

  return { publicFunction };
})();

Naming conventions:

• Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Functions: camelCase
• Modules: PascalCase

Comments:

// 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

grid  // Voronoi diagram + terrain
pack  // Civilizations + derived data
seed  // Random seed

All modules access these globals.

2. Generation Pipeline

generateGrid()
→ generateHeightmap()
→ markFeatures()
→ calculateClimate()
→ generateRivers()
→ defineBiomes()
→ generateCultures()
→ generateStates()
→ render()

Each step builds on the previous.

3. Data Structures

Heavily uses typed arrays:

pack.cells.h = new Uint8Array(n);  // Heights
pack.cells.s = new Uint16Array(n); // State IDs

See Data Model for details.

4. Rendering

Uses D3.js for SVG manipulation:

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:

// 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:

// 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:

"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:

<div id="myEditor" class="dialog">
  <label>My Setting:</label>
  <input id="myInput" type="text" />
</div>

Step 3: Include Script

In index.html, add:

<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
2. Suggest Features - Use 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

Contribution Guidelines

Before Contributing

1. Read the documentation

   • Data Model
   • Architecture
   • Generation Process

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

---

Resources

Documentation

• Home - Wiki home
• Architecture - System design
• Data Model - Data structures
• Generation Process - How maps are created
• Modules Reference - Module documentation
• Features and UI - Feature guide

External Resources

Inspiration:

• Generating Fantasy Maps - Martin O'Leary
• Polygonal Map Generation - Amit Patel
• Here Dragons Abound - Scott Turner

Tools:

• D3.js Documentation
• SVG Reference
• Delaunator

Getting Help

Questions?

• Ask on Discord
• Post on Reddit
• Search GitHub Issues

Bug Reports?

• Use GitHub Issues
• Include steps to reproduce
• Provide browser/version info
• Share console errors

Feature Requests?

• Use 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.

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 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 or contribute code!

---

For more questions, visit the community channels!