Home

Project Zomboid Optimiser (PZO) Wiki

Welcome to the official documentation and technical wiki for Project Zomboid Optimiser (PZO).

PZO is a comprehensive, low-level performance suite and runtime instrumentation engine for Project Zomboid Build 42 and Build 41. It optimizes both desktop clients and dedicated multiplayer servers through live JVM bytecode transformations, native C/C++ hardware acceleration, high-precision timer governors, off-heap network buffer pooling, and multi-core simulation engines.

---

Core Pillars of PZO

1. Client Performance Engine (PZOptimEngine.jar)

• Micro-Stutter Elimination: Elevates OS multimedia timer resolution from 15.6ms down to 1.0ms, synchronizing frame pacing and eliminating micro-freezes.
• Multi-Core Chunk Streaming: Neutralizes thread contention and log locks during fast vehicle travel and map exploration.
• Vanilla Bug Fixes: Patches recursive bugs (such as the IsoGridSquare.isWallTo StackOverflowError bug) directly in memory.
• Deep Memory Caching: Replaces expensive repeated allocations with off-heap page-aligned direct memory pools.
• In-Game F10 Control Center: Real-time telemetry monitoring, thread configuration, and optimization toggles accessible in-game.

2. Dedicated Server Suite (PZOServerEngine.jar)

• Zero-Rubberband Networking: Off-heap Netty direct byte buffer pooling and 4096 UDP datagram sockets for 10-64+ player servers.
• Multi-Threaded Zombie Simulation: Scales ForkJoinPool parallelism across all host CPU cores (up to 32 worker threads) for pathfinding and horde migration.
• Zero-Lag World Saves: 256KB asynchronous disk write buffering for SQLite databases (players.db, vehicles.db) and map chunks.
• Linux & Container Native Sanitizer: Automatically resolves steamclient.so paths and symlinks for Pterodactyl, Docker, and Linux hosts.
• Live Telemetry Daemon: Exports real-time server metrics (TPS, heap usage, GC pause ms, thread counts) to pzo_server_telemetry.json every 5 seconds.

---

Compatibility Matrix

Environment	Supported Versions	Architecture	Optimization Mode
Windows Desktop	Build 42 / Build 41	x86_64 (64-bit)	1-Click Installer (install.bat), Native DLL, JavaAgent
Linux Desktop & Steam Deck	Build 42 / Build 41	x86_64 (64-bit)	Shell script (pzo_optimizer.sh), Native SO, JavaAgent
macOS (Intel & Apple Silicon)	Build 42 / Build 41	x86_64 / Rosetta 2	Command script (pzo_optimizer.command), JavaAgent
Linux Dedicated Servers	Build 42 / Build 41	x86_64 (64-bit)	Headless JavaAgent (-javaagent:PZOServerEngine.jar)
Pterodactyl & Docker Panels	Build 42 / Build 41	x86_64 (64-bit)	Headless JavaAgent (-javaagent:PZOServerEngine.jar)
Android (Zomdroid)	Build 42 / Build 41	ARM64 / box64	JavaAgent (-javaagent), Workshop Lua Mod, Safe Fallback

---

Wiki Navigation

Explore the sections below to get started:

1. Client Installation

   • Automated installers for Windows, Linux, Steam Deck, and macOS.
   • Manual configuration via ProjectZomboid64.json.
   • Verifying engine status in the main menu and in-game.

2. Manual Linux Installation

   • Step-by-step manual setup for Linux desktop, Steam Deck (SteamOS), Flatpak, and headless environments.
   • Staging libpzo_native64.so and configuring Linux JVM flags.
   • Steam Deck Native vs Proton compatibility mode details.

3. Zomdroid (Android) Support

   • Complete setup guide for running PZO on Android via the Zomdroid launcher.
   • Thermal and battery optimization via quarter-resolution fog and memory tuning.
   • Box64 translation compatibility and safe fallback architecture.

4. Server Installation

   • Deploying PZOServerEngine.jar on 3rd-party hosting providers (Pterodactyl, Docker, G-Portal, Indifferent Broccoli, Nitrado).
   • Configuring ProjectZomboid64.json without breaking native Linux launchers.
   • Recommended JVM memory sizing (-Xms and -Xmx).

5. In-Game Features

   • Using the F10 Optimization Control Center.
   • Telemetry overlay and performance tabs.
   • Main menu status indicator and notice modals.

6. Architecture and Optimizations

   • Technical breakdown of bytecode transformations, native C/C++ libraries, and memory governors.
   • How off-heap Netty buffer pooling and multi-core scheduling work.

7. Compatibility and Mods

   • Coexistence with ZombieBuddy (zbNative).
   • Compatibility with workshop mods, overhaul mods, and Java mod loading.

8. Troubleshooting and FAQ

   • Solutions for common errors (e.g. SteamAPI_Init() failed - Steam must be running).
   • Diagnostic checklist and log locations.