PZ Live Map

A DynMap/BlueMap-style live web map for Project Zomboid dedicated servers. Phase 0: static map tiles + real-time player positions. No fog of war, isometric view, or notes yet — see Roadmap.

How it works

PZ's Lua modding sandbox (Kahlua) doesn't expose raw sockets, so a pure Workshop mod can't host a webserver by itself the way a Bukkit/Minecraft plugin can. This project splits the work accordingly:

1. mod/PZLiveMap — a small server-side Lua mod. Drop it in your mods folder like any other mod. It writes online player positions to Zomboid/Lua/PZLiveMap/players.json every ~2 seconds. Nothing else.
2. pz-livemap server binary — a single, dependency-free executable (Go, static binary, no runtime to install) that reads that file and serves the actual web map. Runs as its own small process alongside your game server, on whatever host you're already using.

You point your reverse proxy (or just open the port directly) at the binary, same as you would for any other small web app.

Quick start

1. Install the mod/PZLiveMap mod on your server.
2. Download the pz-livemap binary for your OS from Releases, or build it yourself:

   cd server && ./build.sh
   

3. Copy frontend/ and (once you've generated them, see docs/tile-generation.md) tiles/ next to the binary.
4. Copy server/config.example.json to config.json next to the binary and set players_json to wherever your server actually writes Zomboid/Lua/PZLiveMap/players.json (see below).
5. Run it: ./pz-livemap (or pz-livemap.exe on Windows).
6. Visit http://<your-server-ip>:8091 — or put a reverse proxy in front of it for a real domain + HTTPS.

Finding your players.json path

This depends on how you host PZ:

• Manual / LGSM / bare metal (Linux): usually ~/Zomboid/Lua/PZLiveMap/players.json under whichever user runs the server.
• Windows: %USERPROFILE%\Zomboid\Lua\PZLiveMap\players.json.
• AMP (CubeCoders): under that instance's data directory, typically .../Zomboid/Lua/PZLiveMap/players.json — check your instance's file browser if unsure.
• Pterodactyl / other containerized panels: wherever that panel mounts the server's Zomboid save folder on the host filesystem.

Deployment options

Pick whichever matches how you already run things — none of these are required, they're just process-management choices:

• Run it directly: just execute the binary in a terminal/screen/tmux session. Simplest option, works everywhere.
• AMP Generic Module: register pz-livemap as a second AMP instance pointed at the binary + config, so it starts/stops alongside your PZ instance from the same panel.
• systemd (Linux): see docs/systemd.md for an optional unit file if you want it to survive reboots without AMP or a panel managing it.
• Docker: not provided by default (deliberately — the binary has no dependencies to containerize), but a Dockerfile is trivial to add if your setup wants one; PRs welcome.

Reverse proxy

The binary listens on 127.0.0.1:8091 by default — put whatever you already use in front of it. Example Caddy block in docs/caddy-example.md.

Roadmap

• Static tiles + live player positions
• Fog of war per player
• In-game map notes sync
• Flyer/brochure icons
• Isometric toggle
• Compass heading, darkness overlay, follow mode

Contributing

Issues and PRs welcome, especially around the Lua API calls in mod/PZLiveMap — they're written against the documented B42 API but need real-world testing across different hosting setups.

License

MIT, see LICENSE.