Skip to content

Zomdroid Support and Installation

Jump to bottom
prop11 edited this page Oct 5, 2026 · 3 revisions

Zomdroid (Android) Support & Installation Guide

This guide covers installing and running Project Zomboid Optimiser (PZO) on Android devices using Zomdroid, the open-source Linux translation launcher for Project Zomboid (Build 42 & Build 41).

What is Zomdroid?

Zomdroid is an unofficial community launcher that allows you to play the PC version of Project Zomboid on 64-bit Android smartphones and tablets.

Unlike traditional emulators (such as Winlator or Mobox) which emulate the Windows API and DirectX, Zomdroid utilizes lightweight Linux containerization and box64 translation to run the native Linux PC build of Project Zomboid directly on Android hardware.

Important

Prerequisites for Zomdroid:

  1. You must own a legitimate copy of Project Zomboid on Steam or GOG. Zomdroid does not provide game files and does not condone piracy.
  2. You need the Linux PC version of the game files (downloaded via Steam on PC or via DepotDownloader in Termux).
  3. Android 11+ with a 64-bit ARM processor (ARM64 / AArch64). Snapdragon devices with Adreno GPUs (using Turnip drivers) provide the highest compatibility, smoothest performance, and avoid GL4ES shader include limitations.

Why PZO is Critical for Zomdroid & Mobile Play

Mobile devices face severe constraints that desktop PCs do not: thermal throttling, battery drain, and aggressive Android Low Memory Killer (LMK) daemons.

Stock Project Zomboid generates heavy memory churn, unoptimized full-screen fog fillrate math, and linear line-of-sight loops that can cause mobile phones to overheat and drop to single-digit framerates. PZO directly tackles these bottlenecks:

  1. Single-Pass Quarter-Resolution Fog (FogQuarterBufferGovernor):
    • Stock draws weather fog across 50–100+ separate draw calls across the screen buffer.
    • PZO batches fog into a single GPU draw call at 25% fragment fill rate with bilinear filtering, cutting 75% of GPU fragment math. This drastically reduces mobile GPU heat and power consumption.
  2. Immediate Chunk Streamer Dispatch (StreamerWake):
    • Unparks the chunk loading streamer immediately, reducing mobile stutter when exploring the map or driving.
  3. $O(1)$ Line-of-Sight Visibility Caching (PlayerLosOptimizer):
    • Replaces expensive $O(N)$ linear scans with thread-local hash lookups during zombie encounters.
  4. Blood Decal & Audio Concurrency Capping (Lua Mod):
    • Limits cumulative blood decals and limits overlapping zombie audio voices, preventing mobile audio DSP buffer underruns (crackling) and VRAM exhaustion.
  5. Low-Latency Garbage Collection Tuning:
    • Reduces stop-the-world GC pauses on mobile CPU cores.

Architectural Compatibility Breakdown

PZO is engineered to run seamlessly across PC, server, and translated mobile environments:

PZO Component Zomdroid Compatibility Behavior on Mobile
PZO Steam Workshop Mod (Item 3787481250) 100% Native Executes inside the game's internal Kahlua Lua VM without translation overhead. Controls blood decals, corpse sweeps, and audio throttling. (See note below regarding Build 41 GL4ES shaders).
PZO Java Engine (PZOptimEngine.jar) Native Java Agent Runs directly on the OpenJDK runtime inside the Zomdroid Linux environment via -javaagent:PZOptimEngine.jar. Powers bytecode runtime transformations (fog optimization, LOS caching, chunk streaming).
Agent / Entrypoint Mode Bytecode Agent Mode Zomdroid starts the game using its own custom Android launcher class, so launching via PZOEntrypoint is not used. However, all bytecode optimizations and the Lua bridge run fully via the Java agent (-javaagent).
Native SIMD Library (libpzo_native64.so) Pure Java Fallback Compiled for desktop x86_64 with glibc and AVX2. Because Android uses ARM64, this library cannot load on Android. PZO's built-in safety guard detects this and automatically falls back to 100% pure Java. You do not need to install libpzo_native64.so.
Persistent VBOs Automatic Fallback If the mobile GPU driver does not expose desktop OpenGL 4.4 GL_ARB_buffer_storage, PZO dynamically reverts to standard streaming vertex buffers.

Warning

Build 41 Shaders on the GL4ES Renderer: On Build 41 when using the GL4ES renderer, the workshop mod's replacement shaders with #include directives fail to compile because GL4ES does not expand include utilities (rgb2hsv, hueShift, puddlesMain, performPaddedBodyMask). This causes vehicle, puddle, and tree programs to fail to link. Recommendations:

  • On Snapdragon (Adreno) devices, select the Turnip (Vulkan) renderer in Zomdroid settings instead of GL4ES.
  • If you must use GL4ES on Build 41, avoid activating the mod's replacement shaders (or use vanilla shaders) to prevent missing vehicle textures.

Installation Guide for Zomdroid

Caution

Critical Zomdroid Configuration Rules:

  1. DO NOT edit ProjectZomboid64.json: Zomdroid does not read ProjectZomboid64.json.
  2. DO NOT change or override the classpath: Zomdroid constructs its own internal classpath for Android/box64 containerization. Overriding the classpath replaces Zomdroid's configuration and the game will not start.
  3. Configure all JVM arguments in Zomdroid's Launcher UI: JVM arguments (such as -javaagent and -Xmx) must be entered directly in the Instance Settings inside the Zomdroid app.

Method 1: New Setup / Pre-Packaging

When preparing your Project Zomboid Linux game files before creating your instance ZIP:

Step 1: Download PZOptimEngine.jar

From the PZO Releases page, download PZOptimEngine.jar. (You do NOT need libpzo_native64.so on Android ARM64).

Step 2: Place PZOptimEngine.jar in Game Root

Copy PZOptimEngine.jar directly into the root of your Project Zomboid Linux game files (where projectzomboid.jar resides).

Step 3: Add the Workshop Lua Mod

Copy the PZO Steam Workshop Mod (Folder 3787481250 or Contents/mods/Project-Zomboid-Optimiser) into your game's mods/ directory.

Step 4: Zip and Import into Zomdroid

Select all files inside the game directory (not the parent folder) and compress them into a .zip archive. In Zomdroid, create a new instance and import your ZIP file.

Step 5: Configure JVM Arguments in Zomdroid

  1. Open the Zomdroid app.
  2. Select your instance and tap Edit Settings (gear icon).
  3. Find the JVM Arguments (or Java Arguments) field.
  4. Add the following arguments: 
    -javaagent:PZOptimEngine.jar -Xmx3072m -Xms2048m -XX:+UseG1GC -XX:+AlwaysPreTouch -XX:+UnlockExperimentalVMOptions -XX:+UseSuperWord
  5. Tune -Xmx according to your device's total RAM:
    • 6 GB RAM Devices: Set -Xmx2560m and -Xms1536m
    • 8 GB RAM Devices: Set -Xmx3584m and -Xms2048m
    • 12 GB+ RAM Devices: Set -Xmx5120m and -Xms2048m

Warning

Never set -Xmx to your phone's total RAM! The Android OS, Linux container, and Adreno/Mali GPU all share system memory. Setting -Xmx too high triggers the Android Low Memory Killer (LMK) to terminate the app during map loading.

Method 2: Installing into an Existing Zomdroid Instance

If you already have a working Zomdroid instance on your phone:

  1. Open a mobile file manager (such as ZArchiver, MT Manager, or Solid Explorer).
  2. Navigate to your Zomdroid instance folder:
    • /storage/emulated/0/Android/data/com.zomdroid/files/instances/<InstanceName>/
    • (or /sdcard/Zomdroid/instances/<InstanceName>/)
  3. Copy PZOptimEngine.jar into this instance folder.
  4. Copy the Workshop mod folder into the instance's mods/ directory.
  5. In the Zomdroid app, tap the Settings (gear icon) on that instance.
  6. In JVM Arguments, append: 
    -javaagent:PZOptimEngine.jar -XX:+UseG1GC
    (Ensure -Xmx is set appropriately as shown above).
  7. Save and launch!

Recommended Zomdroid Settings for Optimal Performance

To achieve stable 40–60 FPS on mobile:

1. Zomdroid App Settings

  • Graphics Driver / Renderer:
    • Snapdragon (Adreno): Select Turnip (Vulkan). Turnip provides the highest compatibility, avoids GL4ES shader include limitations, and delivers optimal framerates.
    • MediaTek / Exynos (Mali): Select GL4ES or ANGLE depending on your SoC generation. (See shader notice above for GL4ES).
  • Internal Resolution:
    • Set rendering resolution to 720p (1280x720) or 1080p (1920x1080).
    • Tip: 720p on a 6-inch smartphone display looks crisp while drastically saving GPU fillrate and battery.

2. In-Game Display Options

  • Texture Quality: Medium (saves critical mobile VRAM).
  • Dynamic Puddle Quality: None or Low.
  • Lighting Quality: Low or Medium.
  • Zoom Levels: Uncheck 200% and 250% zoom to reduce offscreen tile generation.

3. PZO In-Game Control Center & Keybindings

Caution

F10 Key Conflict with Zomdroid Backup: In Zomdroid, F10 is already mapped as the built-in backup key! Pressing F10 will trigger an instance backup rather than opening PZO.

  • Recommendation: Remap the PZO Control Center hotkey in mod options, or use an on-screen button / virtual key mapped to an alternate key (such as F9 or F11) to avoid triggering unintended backups during gameplay.

When in the PZO Control Center:

  • Quarter-Res Fog: Keep Enabled (cuts 75% of GPU fog fillrate math).
  • Blood Decal Limiter: Set to Low (500) to prevent memory churn during combat.
  • Corpse Audio Limiter: Keep Enabled to stop audio buffer underruns.

Troubleshooting Mobile & Zomdroid Issues

1. Game Force-Closes Immediately on Launch

  • Cause: You may have modified ProjectZomboid64.json or replaced the classpath. Zomdroid manages its own classpath; altering it breaks the game startup.
  • Fix: Restore your original ProjectZomboid64.json. Put -javaagent:PZOptimEngine.jar strictly in Zomdroid's JVM Arguments inside the instance settings, and never touch the classpath.

2. Game Force-Closes During World Loading (OOM / Signal 9)

  • Cause: Android Low Memory Killer terminated the process because JVM heap plus native memory exceeded available device RAM.
  • Fix: Lower -Xmx in Zomdroid Instance Settings (e.g. from -Xmx4096m down to -Xmx3072m or -Xmx2560m). Close background applications before launching.

3. Build 41 GL4ES Shader Errors (Broken / Invisible Vehicles, Missing Includes)

  • Cause: On Build 41 with the GL4ES renderer, custom replacement shaders that contain #include statements (util/math, util/hueShift, util/bodyMask) fail to compile because GL4ES does not expand includes. Functions like rgb2hsv and performPaddedBodyMask are reported missing, and shaders fail to link.
  • Fix:
    1. On Snapdragon devices: switch your graphics driver in Zomdroid settings from GL4ES to Turnip (Vulkan).
    2. If using GL4ES: disable the mod's custom replacement shaders and use vanilla shaders.
    3. On Build 42, check the dedicated zomdroid branch where shader pipelines are refactored for mobile GLSL 1.20 and 8-sampler limits.

4. F10 Triggers World Backup Instead of PZO

  • Cause: F10 is Zomdroid's built-in backup hotkey.
  • Fix: Map an on-screen custom button or use an alternate key (e.g. F9/F11) for PZO, or configure the hotkey in the PZO Lua options.

5. Native Library (libpzo_native64.so) Warnings in Logs

  • Cause: libpzo_native64.so is compiled for x86_64 desktop Linux with AVX2 and cannot run on ARM64 Android processors.
  • Behavior: This is completely normal and harmless. PZO automatically detects the architecture and falls back to pure Java processing. All key engine optimizations (fog governor, LOS caching, chunk streaming) continue to work in pure Java.

6. Characters and Zombies Appear Solid Red

  • Cause: Desktop shaders using #version 330 fail to compile or link on mobile GL4ES / OpenGLES 2.0 when paired with #version 110 fragment shaders, causing a shader fallback where vertColour evaluates to pure red (1.0, 0.0, 0.0).
  • Fix: Use the dedicated zomdroid branch of PZO. The zomdroid branch converts all character, zombie, and clothing mask shaders to strict GLSL 1.20 with standard attribute and varying syntax and sets clean unit vertex colors.

7. Vehicles Missing Textures or Rendering Pitch Black

  • Cause: Stock desktop vehicle shaders declare 10 texture samplers (including reflection cubemaps). Mobile OpenGLES 2.0 and GL4ES enforce a hardware limit of GL_MAX_TEXTURE_IMAGE_UNITS = 8 (units 0–7). Texture units 8 and 9 fail to bind on mobile GPUs, causing vehicle body textures to drop completely.
  • Fix: Use the zomdroid branch of PZO. The zomdroid branch replaces vehicle shaders with the optimized 8-sampler non-reflection pipeline, ensuring vehicles render with full textures, paint colors, blood, rust, and damage overlays without exceeding mobile texture unit limits.

Community & Resources

Project Zomboid Optimiser (PZO)

External Links

Clone this wiki locally