# 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
``` **Step 3: Include Script** In `index.html`, add: ```html ``` **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!