webographer

Transform Worldographer .wxx map files into interactive D3js visualizations for publishing on the web.

Example Maps

• Pyora by Dungeon Church
• MCDM's Aendrim, mapped by World of Egaar
• Collabris by Matt Colville, mapped by ItsSeaJay/world-of-collabris
• Earth, mapped by Worldographer

Direct Linking to Hexes

Share specific locations using URL parameters:

?x=25&y=12          # Center on hex at column 25, row 12
?x=25&y=12&zoom=3.5 # Also set zoom level

How to Use

1. Add Your Map Files

assets/
├── your-map.wxx              # Your Worldographer map file
└── icons/                    # (Optional) Your icon pack
    ├── worldographer-*.wxx   # Icon config file
    └── *.png                 # Icon images

2. Build

python3 build.py

The build will:

• Find all .wxx map files in assets/
• Extract terrain colors from icon config (if present)
• Generate per-map resources with smart fallbacks
• Create standalone and embed versions

Example output:

Building map: Aendrim - MCDM
  ✓ 38 colors extracted from icon config
  ⚠ 6 generated with fallback
  ✓ 35 icons mapped
  ⚠ 9 terrains use color fill only

3. Test Locally

python3 -m http.server 8000 --directory dist
# Open http://localhost:8000

Development Info

Project Structure

pyora-hex/
├── assets/
│   ├── *.wxx                    # PUT YOUR MAP FILES HERE
│   └── icons/                   # PUT YOUR ICON PACK HERE (optional)
│       └── worldographer-*.wxx  # Icon config (auto-detected)
├── build.py                     # Run this to build
└── dist/                        # Generated output (don't commit)
    ├── index.html               # Map list (or redirect if single map)
    └── {mapname}/
        ├── standalone/          # Full-screen version
        │   ├── index.html
        │   ├── map_data.json
        │   ├── terrain_colors.json
        │   └── terrain_icon_mapping.json
        └── embed/               # Iframe version

What gets generated:

• data/ - Intermediate JSON files (not committed)
• dist/ - Final HTML/JSON/assets (not committed to main)

Deployment

Option 1: Static Hosting (nginx, Apache, etc.)

Copy the dist/ directory to your web server:

rsync -av dist/ user@server:/var/www/your-map/

Option 2: Iframe Embed

Upload the embed/ directory and embed anywhere:

<iframe
  src="https://your-site.com/maps/your-map/embed/index.html"
  width="100%"
  height="600px"
  frameborder="0">
</iframe>

Option 3: Automated CI/CD

The repo includes Forgejo Actions workflow (.forgejo/workflows/build-and-push.yml) that automatically builds and deploys on push to main.

Advanced: Customizing Fallback Colors

The system automatically generates smart fallback colors, but you can customize the logic in src/generate_map_resources.py:

def generate_fallback_color(terrain_name, all_extracted_colors):
    # Category heuristics
    if 'water' in terrain_name.lower():
        return '#006699'  # Blue
    if 'lava' in terrain_name.lower():
        return '#ff4500'  # Orange-red
    # ... customize as needed

Credits

• Built with D3.js
• Map format: Worldographer
• Hex grid math: Red Blob Games
• Worldographer Multicolored Classic Public Domain
• game-icons.net Creative Commons BY 3.0