Client Installation

Client Installation Guide

This guide covers installing and verifying the Project Zomboid Optimiser (PZO) client engine (PZOptimEngine.jar) on Windows, Linux, Steam Deck, and macOS.

---

Prerequisites

1. Project Zomboid: Build 42 (Stable) or Build 41 (Legacy).
2. Steam Workshop Mod (Recommended): Subscribe to Project Zomboid Optimiser to unlock the in-game F10 Control Center UI and main menu telemetry integration.

---

Option 1: Automated 1-Click Installers

Windows

1. Download the latest PZO-Optimizer-Windows.zip from the Releases page.
2. Extract the archive into your Project Zomboid installation directory (typically C:\Program Files (x86)\Steam\steamapps\common\ProjectZomboid\).
3. Double-click install.bat (or launch PZO_Optimizer.exe).
4. The installer automatically detects your game installation, backs up your existing ProjectZomboid64.json, deploys pzo_native64.dll, and attaches PZOptimEngine.jar.
5. Launch Project Zomboid normally through Steam.

---

Linux Desktop & Steam Deck

1. Download PZO_Optimizer_macOS_Linux.zip from the Releases page.
2. Extract the files into your Project Zomboid directory:
   • Standard Linux: ~/.local/share/Steam/steamapps/common/ProjectZomboid/
   • Steam Deck: Switch to Desktop Mode (Power menu > Switch to Desktop), then open Dolphin file manager to the path above.
3. Open a terminal in that folder and make the script executable:

   chmod +x pzo_optimizer.sh
   ./pzo_optimizer.sh

4. The script creates a backup of ProjectZomboid64.json, stages libpzo_native64.so, and configures the JVM launch flags.
5. On Steam Deck, return to Gaming Mode and launch Project Zomboid through Steam.

---

macOS

1. Download PZO_Optimizer_macOS_Linux.zip.
2. Extract the files into your game folder (typically ~/Library/Application Support/Steam/steamapps/common/ProjectZomboid/).
3. Right-click pzo_optimizer.command and choose Open (grant terminal execution permission if prompted).
4. Launch Project Zomboid via Steam.

---

Option 2: Manual Installation

If you prefer configuring files manually without running an installer:

1. Copy PZOptimEngine.jar into your game root directory (where ProjectZomboid64.json is located).
2. If on Windows, copy pzo_native64.dll into the game root. If on Linux, copy libpzo_native64.so into linux64/ or the game root.
3. Open ProjectZomboid64.json in a text editor (e.g. Notepad, VS Code).
4. Add "-javaagent:PZOptimEngine.jar" to the top of your "vmArgs" array:

{
  "mainClass": "zombie/gameStates/MainScreenState",
  "classpath": [
    "PZOptimEngine.jar",
    "java/.",
    "java/projectzomboid.jar"
  ],
  "vmArgs": [
    "-javaagent:PZOptimEngine.jar",
    "-Xmx8192m",
    "-Djava.awt.headless=true",
    "-XX:+UseZGC",
    "-XX:-OmitStackTraceInFastThrow",
    "-XX:+ExitOnOutOfMemoryError"
  ]
}

5. Save the file and launch Project Zomboid via Steam.

---

Verifying Engine Activation

Once Project Zomboid boots, you can confirm PZO is active in two ways:

1. Main Menu Status Icon

Look at the top-right corner of the Project Zomboid main menu:

• Active: Displays the PZO gear/engine icon. Hovering over it shows tooltip: "PZO Engine Active".
• Inactive: Displays a dim icon with tooltip: "PZO Engine Inactive".

2. In-Game F10 Control Center

Press F10 during gameplay:

• If active, Tab 7 ([+] JVM Engine) will be populated with live hardware gauges, real-time GC pause latency (ms), heap usage, and optimization flags.
• If inactive, Tab 7 will prompt you to install the client engine.

---

Uninstallation / Reverting

To uninstall PZO and return to completely stock vanilla settings:

1. Delete PZOptimEngine.jar from your game folder.
2. In Steam, right-click Project Zomboid > Properties > Installed Files > Verify integrity of game files. Steam will restore the stock ProjectZomboid64.json automatically. (Or restore from ProjectZomboid64.json.bak created by the installer).