valheim-map/README.md

Nerdhalla Valheim World Map

Vanilla Valheim community server tools — no mods, no BepInEx. Everything runs off the world save file.

🌐 Live Sites

Site	URL	Purpose
Nerdhalla Community	https://nerdhalla.nerdcade.cc	Map viewer, POI browser, server status
Forgejo (source)	https://git.sweeney.fyi/aelith/valheim-map	Git repo for all code

🗺️ What's Here

Data Pipeline

Step	Script	Output
Decode tiles	decode_valheim_tiles.py	16 × 1024×1024 PNGs (composite, biome, height)
Stitch tiles	valheim_decode_tiles.py	4096×4096 world images
Build POI DB	build_db.py	SQLite DB with 11,309 locations
Build viewer	build_viewer.py	Leaflet HTML with 3 map layers
Parse .db	parse_valheim_db.py	ZPackage → JSON conversion

Web Viewer (index.html)

• Leaflet map with 3 layers: composite, biome, height
• 11,309 POI markers with category icons (boss, dungeon, resource, etc.)
• Coordinate display on hover
• POI browser with search + category filter
• Server status indicator (checks Nerdcade via SSH)

API Server (api_server.py)

• GET /api/status — Nerdcade server online/offline check
• GET /api/pois?limit=N&search=X&category=Y — POI queries

Infrastructure

• Caddy — reverse proxy with auto-TLS for nerdhalla.nerdcade.cc + git.sweeney.fyi
• Forgejo — bare metal (migrated from Docker), git.sweeney.fyi:3000
• nerdhalla-api — systemd service, port 8081

📊 World Stats

Property	Value
Seed	yzZ5fr2tGa
Map Size	~10 km × 10 km (4096 × 4096 px)
Biomes	Meadows, Black Forest, Swamp, Mountain, Plains, Ocean, Mistlands
Total POIs	11,309
Best Tar Pit	(1210, -4159) — 5 tar pits within 200m

🚧 Roadmap

Phase 1 — POI Database ✅

• Decode 16 map tiles from world save
• Stitch into 4096×4096 composite/biome/height images
• Build SQLite DB from locations.json (11,309 POIs)
• Spatial queries for base location hunting

Phase 2 — Web Viewer ✅

• Leaflet map with 3 tile layers
• POI markers with category icons
• Search + category filter
• Coordinate display
• Server status indicator
• TLS via Caddy
• API backend for POI queries

Phase 3 — Fog-of-War ⏳

• Blocked: Need player .fch files from local machines
• Extract explored/unexplored bitmap per player
• Overlay on map viewer
• Merge multiple players' exploration data

Phase 4 — Cartography Sync 🔮

• Undecided approach:
  • Option 1: ServerSideMap mod (requires BepInEx — some players don't want this)
  • Option 2: Periodic merge script (pull .fch files, merge explored data)
  • Option 3: Cartography table automation (in-game solution)

Phase 5 — Automation 🔮

• Cron job to periodically pull Nerdhalla.db from Nerdcade
• Auto-regenerate map tiles on world update
• Push updated data to site

🛠️ Infrastructure

Services on Boston-VPS

Service	Type	Port	Notes
Caddy	Bare metal	80/443	Reverse proxy, auto-TLS
Forgejo	Bare metal	3000	Git server, git.sweeney.fyi
nerdhalla-api	Bare metal	8081	Python API server
Hermes Gateway	Bare metal	8642/8644	Fleet COO agent

Docker Cleanup (June 2026)

• Forgejo migrated from Docker to bare metal (saved ~450 MB virtual overhead)
• Dead containers removed: hermes-fa98be67 (exited), vllm-compression (never started)
• 9.2 GB reclaimed from unused images
• Docker still installed but only used if needed

🔧 Quick Commands

# Restart API
sudo systemctl restart nerdhalla-api

# Restart Forgejo
sudo systemctl restart forgejo

# Restart Caddy
sudo systemctl reload caddy

# View logs
sudo journalctl -u nerdhalla-api -n 50 --no-pager
sudo journalctl -u forgejo -n 50 --no-pager
sudo tail -f /var/log/caddy/nerdhalla.log

📁 File Layout

/var/www/nerdhalla/          # Site root
├── index.html               # Main site
├── api_server.py            # Python API
├── world_composite.png      # 4096×4096 map images
├── world_biome.png
├── world_height.png
├── 00-00_*.png              # Individual tile images (16 tiles × 3 layers)
└── ...

/srv/forgejo/                # Forgejo data
└── data/
    ├── gitea/               # Config, DB, attachments
    └── git/repositories/    # Git repos

/etc/caddy/
├── Caddyfile                # Main config (imports sites-enabled/)
└── sites-enabled/
    ├── nerdhalla.conf       # nerdhalla.nerdcade.cc
    └── git.conf             # git.sweeney.fyi

🔗 Related

• Nerdcade server: aelith@100.86.206.39:46129
• World saves: /home/amp/.ampdata/instances/Valheim/.config/unity3d/IronGate/Valheim/worlds_local/
• Forgejo API token: stored in Hermes memory