Server Installation

Dedicated Server Installation Guide

This guide covers installing and configuring the PZO Server Engine (PZOServerEngine.jar) on dedicated servers, virtual private servers (VPS), and 3rd-party game server control panels.

Supported hosts include: Pterodactyl Panels, Docker containers, Indifferent Broccoli, G-Portal, Nitrado, GTXGaming, BisectHosting, Hetzner, OVH, and Windows Server.

---

Why Use the PZO Server Engine?

Running a dedicated Project Zomboid server with 10-64+ players often causes:

1. Multiplayer Rubberbanding: High-speed driving or horde combat causes UDP datagram drops and player desync.
2. Periodic Server Freezes: World auto-saves to SQLite databases (players.db, vehicles.db) and map chunk files pause the main game loop.
3. CPU Bottlenecks: Vanilla zombie pathfinding and simulation run mostly on a single tick thread.

PZOServerEngine.jar resolves these bottlenecks through off-heap direct Netty memory buffer pooling, 4096 UDP datagram sockets, multi-threaded ForkJoinPool zombie simulation, and 256KB asynchronous disk write buffering.

---

Installation Steps (Pterodactyl / Docker / Web Panels)

Step 1: Upload PZOServerEngine.jar

Using your hosting panel's File Manager or an SFTP/FTP client (FileZilla / WinSCP):

1. Download PZOServerEngine.jar from the latest release on GitHub.
2. Upload PZOServerEngine.jar into your server's root directory (the folder containing ProjectZomboid64.json or projectzomboid.jar).

---

Step 2: Configure ProjectZomboid64.json

Open ProjectZomboid64.json in your host's File Manager:

1. CRITICAL FOR LINUX / PTERODACTYL: Keep "mainClass": "zombie/network/GameServer" untouched!

   Why? The native Linux launcher binary (ProjectZomboid64) checks if mainClass matches "zombie/network/GameServer". If mainClass is changed, the binary assumes it is booting a desktop client and triggers a failing SteamAPI_Init() check that crashes the server before Java starts.

2. Add "-javaagent:PZOServerEngine.jar" to the top of the "vmArgs" array.

Complete ProjectZomboid64.json Example:

{
  "mainClass": "zombie/network/GameServer",
  "classpath": [
    "java/.",
    "java/projectzomboid.jar"
  ],
  "vmArgs": [
    "-javaagent:PZOServerEngine.jar",
    "-Djava.awt.headless=true",
    "-Xmx8192m",
    "-Dzomboid.server=1",
    "-Dzomboid.steam=1",
    "-Dzomboid.znetlog=1",
    "-Djava.library.path=linux64/",
    "-Djava.security.egd=file:/dev/urandom",
    "-XX:+UseZGC",
    "-XX:-OmitStackTraceInFastThrow",
    "-XX:+UseCompactObjectHeaders",
    "-XX:+UseStringDeduplication",
    "-XX:+PerfDisableSharedMem",
    "-XX:+DisableExplicitGC",
    "-XX:+ExitOnOutOfMemoryError"
  ]
}

3. Save the file and restart your server from your host web panel.

---

Linux & Docker Steam Environment Notes

On headless Linux servers and Docker containers, Steamworks native libraries require proper location linking:

1. steam_appid.txt: Ensure a file named steam_appid.txt exists in your server root directory containing the text:

   108600
   

2. steamclient.so Automatic Resolution: PZOServerEngine.jar includes a built-in LinuxSteamServerSanitizer that scans /home/container/, /home/steam/, and linux64/, automatically pre-loading steamclient.so and creating the required symlink at ~/.steam/sdk64/steamclient.so.
3. Manual Fallback Command (if your host blocks automatic symlinking): In your server terminal or startup command, run:

   mkdir -p ~/.steam/sdk64 && cp -f linux64/steamclient.so ~/.steam/sdk64/

---

Recommended Host RAM Allocation

Match your -Xms (minimum heap) and -Xmx (maximum heap) parameters to your server hosting plan:

Server Host Plan	Recommended -Xms	Recommended -Xmx	Player Capacity
4 GB Plan	-Xms1536m	-Xmx3584m	1 - 4 Players
6 GB Plan	-Xms2048m	-Xmx5120m	4 - 8 Players
8 GB Plan	-Xms2048m	-Xmx7168m	8 - 16 Players
16 GB Plan	-Xms4096m	-Xmx14336m	16 - 32 Players
32 GB+ Dedicated	-Xms8192m	-Xmx28672m	32 - 64+ Players

Important: Never allocate 100% of your container's RAM to -Xmx. Always reserve at least 512MB to 1GB for the operating system, off-heap Netty direct memory buffers, and native C++ libraries (RakNet, FMOD, SQLite). If the container exceeds its RAM limit, the host (e.g. Pterodactyl Wings) will kill the process (OOMKilled).

---

Live Server Telemetry & Discord Bot Integration

PZOServerEngine.jar runs a lightweight, low-priority background daemon that updates pzo_server_telemetry.json every 5 seconds inside your server's Zomboid/Lua/ directory.

Example JSON Payload:

{
  "server_optimized": true,
  "max_mb": 8192,
  "used_mb": 2410,
  "free_mb": 5782,
  "gc_count": 14,
  "gc_pause_avg_ms": 1,
  "threads": 42,
  "cpu_percent": 18.5,
  "timestamp": 1725807600000
}

Server administrators can write simple Discord bots or shell scripts to tail this file and monitor server health, active threads, and garbage collection pauses in real time.