diff --git a/.gitignore b/.gitignore index b0a273f0..2ea17d1d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ /node_modules /dist /coverage +CONTRIBUTING-UPSTREAM.md diff --git a/GRID-NUMBERING-README.md b/GRID-NUMBERING-README.md new file mode 100644 index 00000000..7ea6ce65 --- /dev/null +++ b/GRID-NUMBERING-README.md @@ -0,0 +1,250 @@ +# Grid Auto-Numbering Feature for Azgaar Fantasy Map Generator + +## Overview + +Added sequential auto-numbering to the grid overlay system, allowing users to reference specific grid cells (e.g., "POI located in grid 0247"). Numbers are displayed centered within each grid cell with customizable size and color. + +## Features Added + +- ✅ Sequential numbering starting from top-left (0001, 0002, 0003...) +- ✅ Works with: **Pointy Hex**, **Square**, and **Truncated Square** grids +- ✅ Customizable font size (1-50px) +- ✅ Customizable color +- ✅ Toggle on/off via checkbox +- ✅ Proper centering in grid cells +- ✅ Full map coverage + +## Known Limitations + +**Grid Types Not Yet Supported**: +The following grid types require additional positioning calculations and are not currently supported: +- ❌ Hex grid (flat) +- ❌ Square 45 degrees grid +- ❌ Tetrakis square grid +- ❌ Triangle grid (horizontal) +- ❌ Triangle grid (vertical) +- ❌ Trihexagonal grid +- ❌ Rhombille grid + +The numbering feature will display on these grid types but numbers will not align correctly with cell centers. Each grid type has unique geometry that requires specific positioning logic in the `getGridCellCenter()` function. + +## Files Modified + +### 1. `index.html` +**Location**: Lines 889-910 (in `` section) + +**Changes**: Added UI controls for grid numbering in the Style panel: +```html + + + + + + + + + Number size + + + + + + + Number color + + + #808080 + + +``` + +### 2. `modules/ui/layers.js` +**Location**: Lines 657-661, 664-754 + +**Changes**: +1. Modified `drawGrid()` function to call `drawGridNumbers()` when enabled +2. Added three new functions: + - `drawGridNumbers()` - Main rendering logic + - `getGridCellDimensions()` - Returns cell dimensions for each grid type + - `getGridCellCenter()` - Calculates center position for each cell + +**Key Implementation Details**: + +```javascript +// In drawGrid() - Line 657-661 +const showNumbers = gridOverlay.attr("data-show-numbers") === "1"; +if (showNumbers) { + drawGridNumbers(maxWidth, maxHeight, scale, dx, dy); +} +``` + +### 3. `modules/ui/style.js` +**Location**: Lines 212-215 (initialization), 520-525 (declarations), 543-557 (event handlers) + +**Changes**: +1. Added variable declarations for UI elements +2. Added initialization code to read grid numbering attributes +3. Added event handlers for checkbox, size input, and color picker + +```javascript +// Variable declarations (after styleGridType handler) +const styleGridShowNumbers = byId("styleGridShowNumbers"); +const styleGridNumberSize = byId("styleGridNumberSize"); +const styleGridNumberColor = byId("styleGridNumberColor"); +const styleGridNumberColorOutput = byId("styleGridNumberColorOutput"); + +// Initialization in selectStyleElement() +styleGridShowNumbers.checked = el.attr("data-show-numbers") === "1"; +styleGridNumberSize.value = el.attr("data-number-size") || 8; +styleGridNumberColor.value = styleGridNumberColorOutput.value = + el.attr("data-number-color") || "#808080"; + +// Event handlers +styleGridShowNumbers.on("change", function () { + getEl().attr("data-show-numbers", this.checked ? "1" : "0"); + if (layerIsOn("toggleGrid")) drawGrid(); +}); + +styleGridNumberSize.on("input", function () { + getEl().attr("data-number-size", this.value); + if (layerIsOn("toggleGrid")) drawGrid(); +}); + +styleGridNumberColor.on("input", function () { + styleGridNumberColorOutput.value = this.value; + getEl().attr("data-number-color", this.value); + if (layerIsOn("toggleGrid")) drawGrid(); +}); +``` + +## Position Calculation Math + +### Pointy Hex Grid Positioning + +After extensive testing and calibration, the following values provide perfect alignment: + +**Row Spacing**: `cellHeight * 0.5` +- This is different from the geometric ideal of 0.75 +- Empirically determined through visual alignment with hex centers + +**Y-Offset (Vertical Center)**: `cellHeight * 0.35` +- Positions numbers vertically within hex +- Accounts for hex shape geometry + +**X-Offset (Horizontal Center)**: `cellWidth / 2` +- Standard horizontal centering + +**Row Offset Pattern**: Even rows (0, 2, 4...) are shifted right by `cellWidth / 2` +- This creates the interlocking hex pattern + +### Grid Cell Dimensions (Base Size) + +From SVG pattern definitions: +- Pointy Hex: width=25, height=43.4 +- Flat Hex: width=43.4, height=25 +- Square: width=25, height=25 +- (Other grid types defined in `getGridCellDimensions()`) + +### Row/Column Count Calculation + +```javascript +const rowSpacing = cellHeight * 0.5; +const cols = Math.ceil(maxWidth / cellWidth) + 2; +const rows = Math.ceil(maxHeight / rowSpacing) + 2; +``` + +Note: Adding +2 ensures full map coverage including edges. + +## How to Use + +### For Users: + +1. Enable the **Grid** layer (press `G` or click Grid toggle) +2. Open **Style** panel (right sidebar) +3. Select **"Grid"** from the element dropdown +4. Check **"Show grid numbers"** checkbox +5. Adjust **Number size** and **Number color** as desired + +### For Developers: + +Grid numbering state is stored as attributes on the `gridOverlay` SVG element: +- `data-show-numbers`: "1" or "0" +- `data-number-size`: Number (default 8) +- `data-number-color`: Hex color (default "#808080") + +These can be set programmatically: +```javascript +gridOverlay.attr("data-show-numbers", "1"); +gridOverlay.attr("data-number-size", "12"); +gridOverlay.attr("data-number-color", "#000000"); +drawGrid(); +``` + +## Testing & Calibration Process + +The positioning values were determined through iterative testing: + +1. Started with theoretical hex geometry (0.75 row spacing) +2. User placed visual markers at hex centers +3. Adjusted row spacing and Y-offset incrementally +4. Final values: rowSpacing=0.5, Y-offset=0.35 + +This empirical approach accounts for any rendering quirks or pattern definition nuances. + +## Performance Considerations + +- Numbers are rendered as SVG text elements +- Typical full map: ~3000 grid cells +- Negligible performance impact on modern browsers +- Numbers are part of the gridOverlay group and clear when grid is toggled off + +## Future Enhancement Ideas + +- Save grid numbering preference to localStorage +- Export numbered grid with map export +- Click-to-copy grid number functionality +- Custom numbering patterns (A1, A2... or hex coordinates) +- Grid number search/highlight feature + +## Technical Notes + +### Why Not Pure Geometric Spacing? + +The theoretical vertical spacing for pointy hex grids is `1.5 × sideLength = 0.75 × height`. However, we use `0.5 × height` because: + +1. SVG pattern rendering may introduce sub-pixel differences +2. The pattern definition includes the full hex perimeter path +3. Visual alignment matters more than mathematical purity +4. The 0.5 value was empirically validated against user-placed markers + +### Edge Case Handling + +- Numbers extend slightly beyond visible map area (+2 buffer) +- Partial hex cells at edges still receive numbers +- Zoom level doesn't affect numbering (numbers don't scale) + +## Implementation Summary + +**Total Lines of Code Added**: ~150 +**Files Modified**: 3 +**New Functions Added**: 3 +**UI Controls Added**: 3 + +This implementation integrates cleanly with Azgaar's existing grid system without modifying core rendering logic. All grid numbering code is isolated and can be easily maintained or removed. + +## Credits + +Implementation developed through collaborative debugging session, December 2024. +Tested on Azgaar Fantasy Map Generator (latest version as of Dec 2024). + +## Contact & Contribution + +If integrating this into the official Azgaar repository, consider: +- Adding grid numbering to the style presets +- Including in map export metadata +- Adding to the wiki documentation +- Internationalizing the UI labels + +--- + +**License**: Same as Azgaar Fantasy Map Generator (MIT) diff --git a/README.md b/README.md index 3ab245b2..1acad4e5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,79 @@ +# Azgaar Fantasy Map Generator - Enhanced Fork + +This is a personal fork of [Azgaar's Fantasy Map Generator](https://github.com/Azgaar/Fantasy-Map-Generator) with custom enhancements for D&D campaign management. + +## Original Project + +**Original Repository**: [Azgaar/Fantasy-Map-Generator](https://github.com/Azgaar/Fantasy-Map-Generator) +**Original Author**: Max Haniyeu (Azgaar) +**License**: MIT License + +Full credit to Azgaar for creating this incredible fantasy map generation tool. Please visit and star the original repository! + +--- + +## Custom Enhancements in This Fork + +### ✨ Grid Auto-Numbering Feature + +Added sequential numbering to grid cells for easy location referencing in D&D campaigns. + +**Features:** +- Sequential numbering (0001, 0002, 0003...) starting from top-left +- Customizable font size and color +- Toggle on/off in Style panel +- Perfect alignment for pointy hex, square, and truncated square grids + +**Usage:** +1. Enable Grid layer (press `G`) +2. Open Style panel → Select "Grid" +3. Check "Show grid numbers" +4. Adjust size and color as desired + +**Documentation:** See [`GRID-NUMBERING-README.md`](./GRID-NUMBERING-README.md) for full implementation details. + +--- + +## Running Locally + +```bash +# Clone this fork +git clone [your-fork-url] +cd Fantasy-Map-Generator + +# Open in browser +# Just open index.html in your web browser +``` + +--- + +## Contributing Back to Original Project + +If you're interested in the grid numbering feature, please check out the [original Azgaar repository](https://github.com/Azgaar/Fantasy-Map-Generator) and consider starring it! The feature could potentially be contributed upstream if there's interest. + +--- + +## License + +This fork maintains the original MIT License. See [LICENSE](./LICENSE) for full details. + +**Copyright 2017-2024 Max Haniyeu (Azgaar)** +Grid numbering enhancements © 2024 + +--- + +## Acknowledgments + +- **Azgaar** - For creating and maintaining this fantastic map generator +- **Original Contributors** - Everyone who has contributed to the main project +- **D&D Community** - For inspiration and use cases + +--- + +**Original README follows below:** + +--- + # 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. diff --git a/images/fantasy-icons/battlefield.svg b/images/fantasy-icons/battlefield.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/battlefield.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/bridge.svg b/images/fantasy-icons/bridge.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/bridge.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/brigand.svg b/images/fantasy-icons/brigand.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/brigand.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/burial.svg b/images/fantasy-icons/burial.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/burial.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/canoe.svg b/images/fantasy-icons/canoe.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/canoe.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/cave.svg b/images/fantasy-icons/cave.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/cave.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/circus.svg b/images/fantasy-icons/circus.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/circus.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/dance.svg b/images/fantasy-icons/dance.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/dance.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/dungeon.svg b/images/fantasy-icons/dungeon.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/dungeon.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/encounter.svg b/images/fantasy-icons/encounter.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/encounter.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/fair.svg b/images/fantasy-icons/fair.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/fair.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/forest.svg b/images/fantasy-icons/forest.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/forest.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/hot-spring.svg b/images/fantasy-icons/hot-spring.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/hot-spring.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/inn.svg b/images/fantasy-icons/inn.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/inn.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/joust.svg b/images/fantasy-icons/joust.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/joust.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/library.svg b/images/fantasy-icons/library.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/library.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/lighthouse.svg b/images/fantasy-icons/lighthouse.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/lighthouse.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/migration.svg b/images/fantasy-icons/migration.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/migration.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/mine.svg b/images/fantasy-icons/mine.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/mine.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/mirage.svg b/images/fantasy-icons/mirage.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/mirage.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/monster.svg b/images/fantasy-icons/monster.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/monster.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/necropolis.svg b/images/fantasy-icons/necropolis.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/necropolis.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/pirate.svg b/images/fantasy-icons/pirate.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/pirate.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/placeholder.svg b/images/fantasy-icons/placeholder.svg new file mode 100644 index 00000000..61bbe765 --- /dev/null +++ b/images/fantasy-icons/placeholder.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/images/fantasy-icons/portal.svg b/images/fantasy-icons/portal.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/portal.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/rift.svg b/images/fantasy-icons/rift.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/rift.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/ruins.svg b/images/fantasy-icons/ruins.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/ruins.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/sacred-mountain.svg b/images/fantasy-icons/sacred-mountain.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/sacred-mountain.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/sea-monster.svg b/images/fantasy-icons/sea-monster.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/sea-monster.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/statue.svg b/images/fantasy-icons/statue.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/statue.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/volcano.svg b/images/fantasy-icons/volcano.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/volcano.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/water-source.svg b/images/fantasy-icons/water-source.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/water-source.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/images/fantasy-icons/waterfall.svg b/images/fantasy-icons/waterfall.svg new file mode 120000 index 00000000..ffbb4841 --- /dev/null +++ b/images/fantasy-icons/waterfall.svg @@ -0,0 +1 @@ +placeholder.svg \ No newline at end of file diff --git a/index.css b/index.css index 373bf63c..e9066a91 100644 --- a/index.css +++ b/index.css @@ -2421,3 +2421,4 @@ svg.button { background: #25252a; } } +.grid-label { font-size: 10px; font-family: sans-serif; pointer-events: none; text-shadow: 1px 1px 0 #fff, -1px -1px 0 #fff, 1px -1px 0 #fff, -1px 1px 0 #fff; } diff --git a/index.html b/index.html index 5a18e579..3944ae2a 100644 --- a/index.html +++ b/index.html @@ -1,8184 +1,6222 @@ - - - - Azgaar's Fantasy Map Generator - - - - + + + - - - + Azgaar's Fantasy Map Generator + + + + - - - - - - + + + - - + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + 100% { + opacity: 0.1; + } + } - - - - - - - - - + @keyframes spin { + 0% { + transform: rotate(0deg); + } - - - - - - - - - + 100% { + transform: rotate(359deg); + } + } + - - - - - - - - - - - - - + + + + - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + + + + + + + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - -
- - - - - - - -
-
Azgaar's
-
Fantasy Map Generator
-
‎ ‎
-

LOADING...

-
+ + + + + + + + + + + + + + + + + + +
+ + + + + + + +
+
Azgaar's
+
Fantasy Map Generator
+
‎ ‎
+

LOADING...

+
+
+ +
+
+ +
-
-
- - + + + + +
-