ZombieBuddy

A powerful framework for Project Zomboid modders that enables Java bytecode manipulation and runtime patching of game classes using ByteBuddy.

What is ZombieBuddy?

<img src="icon_256.png" align="right" alt="ZombieBuddy Icon" width="128" height="128">

ZombieBuddy is a Java agent-based framework that allows modders to:

• Patch game classes at runtime using bytecode manipulation
• Expose Java classes to Lua for enhanced modding capabilities
• Apply patches declaratively using simple annotations
• Load Java code from mods seamlessly

Built on top of ByteBuddy, ZombieBuddy provides a clean, annotation-based API for intercepting and modifying game behavior without requiring access to the game's source code.

Developer / Debug helpers

See doc/DevDebugFunctions.md for Lua dev/debug utilities (zbinspect, zbmethods, zbgrep, zbmap, zbgreplog, etc.) exposed by ZombieBuddy for introspecting and manipulating game/Java objects at runtime.

☕ Support the Project

If you find ZombieBuddy useful and would like to support its development, consider buying me a coffee! Your support helps keep this project maintained and improved.

Why ZombieBuddy?

Previously, Java mods for Project Zomboid required bundling .class files and manually replacing game files to work. ZombieBuddy makes this process much better:

1. No manual file replacement: ZombieBuddy automatically loads and applies patches at runtime - no need to manually copy .class files into the game's installation directory.

2. Precise patching: Instead of replacing entire class files, you can patch specific methods with surgical precision. This means:

   • Multiple mods can patch the same class without conflicts
   • Updates to the game are less likely to break your mod
   • You only modify what you need, leaving the rest of the class intact

Features

• 🎯 Annotation-based patching: Use @Patch annotations to declare method patches
• 🔄 Runtime class transformation: Patch classes that are already loaded using retransformation
• 📦 Automatic patch discovery: Scans for patch classes automatically
• 🔗 Lua integration: Expose Java classes and global functions to Lua via annotations (@Exposer.LuaClass, @LuaMethod(global = true)) or the Exposer API; built-in ZombieBuddy.Events for inspecting game event hooks, and ZombieBuddy.Watches (experimental) for hooking any Java method and logging calls
• ⚡ Advice and Method Delegation: Support for both advice-based and delegation-based patching
• 🔍 Verbose logging: Configurable verbosity levels for debugging

Installation

For End Users

⚠️ SECURITY WARNING: Unlike Lua mods which run in a sandboxed environment, Java mods are completely unrestricted and can execute any code with full system permissions. By installing ZombieBuddy and enabling Java mods, you are granting them the ability to:

• Access and modify any game files or data
• Access your file system outside the game directory
• Perform network operations
• Execute any Java code without restrictions

Only install and enable Java mods from sources you trust completely. Review the source code if available, and be aware that malicious Java mods could potentially harm your system or compromise your data. You install and use Java mods at your own risk.

🪟 Windows (Automated Installer)

The easiest way to install ZombieBuddy on Windows is using the automated installer:

1. Download the latest ZombieBuddyInstaller.exe from the GitHub Releases page.
2. Run the installer. It will automatically:
   • Detect your Steam and Project Zomboid installation folders.
   • Find the ZombieBuddy Workshop content (ensure you are subscribed on Steam).
   • Copy zbNative.dll and ZombieBuddy.jar to your game directory.
   • Update your Steam launch options to include -agentlib:zbNative --.
3. Restart Steam for the changes to take effect.

Note: The installer handles everything for you. You don't need to manually copy files or edit launch options.

🐧 macOS and Linux (Manual Installation)

ZombieBuddy requires manual installation on these platforms as it runs as a Java agent. Follow the steps in the Manual Installation section below.

🛠️ Manual Installation (Fallback for Windows)

If you prefer to install manually on Windows, or are on macOS/Linux, follow these steps:

1. Download the mod from the Steam Workshop or GitHub releases

2. Extract the mod to your Project Zomboid mods directory:

   • Windows: %USERPROFILE%\Zomboid\mods\ZombieBuddy\
   • Linux/Mac: ~/Zomboid/mods/ZombieBuddy/

3. Copy files to the game directory:

   macOS and Linux:

   • Copy ZombieBuddy.jar from the mod's build/libs/ directory to:
     • macOS: ~/Library/Application Support/Steam/steamapps/common/ProjectZomboid/Project Zomboid.app/Contents/Java/
     • Linux: The equivalent Java directory in your Steam installation (typically ~/.steam/steam/steamapps/common/ProjectZomboid/projectzomboid/)

   Windows:

   • Copy both ZombieBuddy.jar and zbNative.dll from the mod's build/libs/ directory to the game directory:
     • Typically: C:\Program Files (x86)\Steam\steamapps\common\ProjectZomboid\
     • Or wherever your Steam installation is located

   Note: On Windows, zbNative.dll is required because the JRE hardcodes the path to jre64\bin\instrument.dll, which depends on java.dll and jli.dll that are not on the DLL load path. The native loader adds jre64\bin to the DLL load path and then proxies calls to instrument.dll. Source code for zbNative.dll is provided in the repository.

Why is zbNative.dll needed on Windows?

On Windows, when using -javaagent:ZombieBuddy.jar, the JRE attempts to load jre64\bin\instrument.dll (the path is hardcoded in the JRE). However, this DLL depends on java.dll and jli.dll, which are also located in jre64\bin but are not on the DLL load path. This causes the loading of instrument.dll to fail.

The solution is zbNative.dll, a native library that:

1. Adds jre64\bin to the DLL load path
2. Proxies calls to instrument.dll
3. Automatically loads ZombieBuddy.jar as a Java agent
4. Handles automatic updates: On startup, zbNative.dll checks if ZombieBuddy.jar.new exists (created when a newer version is detected via Steam mod update but the JAR couldn't be replaced during runtime). If found, it automatically replaces ZombieBuddy.jar with the new version before loading it.

This is why Windows users must:

• Copy both ZombieBuddy.jar and zbNative.dll to the game directory
• Use only -agentlib:zbNative -- in launch options (it automatically loads ZombieBuddy.jar)

On macOS and Linux, this workaround is not needed, so only ZombieBuddy.jar is required and you use -javaagent:ZombieBuddy.jar -- directly.

4. Modify game launch options:

   • Open Steam and go to Project Zomboid properties
   • Navigate to "Launch Options" or "Set Launch Options"
   • Add one of the following (see screenshot below):

   macOS and Linux:

   -javaagent:ZombieBuddy.jar --
   

   Or with verbosity for debugging (shows patch transformations):

   -javaagent:ZombieBuddy.jar=verbosity=1 --
   

   Or with maximum verbosity (shows all debug output):

   -javaagent:ZombieBuddy.jar=verbosity=2 --
   

   Windows:

   -agentlib:zbNative --
   

   Or with verbosity for debugging:

   -agentlib:zbNative=verbosity=1 --
   

   Or with maximum verbosity:

   -agentlib:zbNative=verbosity=2 --
   

   Note: zbNative.dll automatically loads ZombieBuddy.jar as a Java agent, so you don't need to specify -javaagent:ZombieBuddy.jar separately.

   • ⚠️ IMPORTANT: The -- at the end is mandatory - do not omit it!
   • Windows users: Only -agentlib:zbNative -- is required (it automatically loads ZombieBuddy.jar)
   • Verbosity levels:
     • verbosity=0 (default): Errors only
     • verbosity=1: Shows patch transformations
     • verbosity=2: Shows all debug output

5. Enable the mod in the Project Zomboid mod manager (if you want to use mods that depend on ZombieBuddy)

6. Launch the game - ZombieBuddy will load automatically as a Java agent

7. Verify installation: You can confirm ZombieBuddy is working by checking:

   • Game version string: Look for [ZB] appended to the game version (e.g., "Build 42.30.16 [ZB]")
   • Loading screen: The ZombieBuddy version (e.g., "ZB 1.0.2") appears at the bottom right corner during game loading
   • Main menu: The ZombieBuddy version is visible at the bottom right corner of the main menu screen

Steam Launch Options Configuration:

For Modders

ZombieBuddy enables you to create Java mods that can patch game classes and expose Java functionality to Lua. Here's how to build a Java mod:

1. Set Up Your Mod Structure

Create a standard Project Zomboid mod structure:

YourMod/
├── [version]/
│   ├── mod.info
│   └── media/
│       └── java/
│           └── YourMod.jar
└── common/

2. Configure mod.info

Add the following entries to your mod.info file:

require=\ZombieBuddy
javaJarFile=media/java/YourMod.jar
javaPkgName=com.yourname.yourmod
ZBVersionMin=1.0.0
ZBVersionMax=1.5.0

• require=\ZombieBuddy: Declares dependency on ZombieBuddy framework
• javaJarFile: Path to your JAR file relative to the mod version directory. Required if you want to load Java code. Note: Only a single JAR file is supp