# 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 ✅
- [x] Decode 16 map tiles from world save
- [x] Stitch into 4096×4096 composite/biome/height images
- [x] Build SQLite DB from `locations.json` (11,309 POIs)
- [x] Spatial queries for base location hunting

### Phase 2 — Web Viewer ✅
- [x] Leaflet map with 3 tile layers
- [x] POI markers with category icons
- [x] Search + category filter
- [x] Coordinate display
- [x] Server status indicator
- [x] TLS via Caddy
- [x] 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

```bash
# 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