zed-0xff /ZombieBuddy

Java agent framework for Project Zomboid that enables runtime bytecode patching using ByteBuddy. Annotation-based API for modding game classes without source code access.

★ 356⑂ 91👁 3⑃ 80● 60▤ 6
JavaMITCreated 2025-12-03
下载:Windows Installer 4.4windows_installer_4.4 ↓4.42026-10-20
+7
日增长
356
stars
91
forks
3
watchers
80
prs
60
issues
6
releases

README

ZombieBuddy

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

 What is ZombieBuddy?



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.

 Why ZombieBuddy?

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

1. No manual file replacement: Automatically loads and applies patches at runtime
2. Precise patching: Patch specific methods with surgical precision - multiple mods can patch the same class without conflicts, and game updates are less likely to break your mod

 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
- ⚡ Advice and Method Delegation: Support for both advice-based and delegation-based patching
- 🔍 Verbose logging: Configurable verbosity levels for debugging

 Quick Start

 For End Users

1. Windows: Download and run ZombieBuddyInstaller.exe, then choose the launch modes to patch. The installer also has an uninstall option and shows a confirmation preview before applying changes.
2. macOS/Linux: Copy ZombieBuddy.jar to the game directory and add -javaagent:ZombieBuddy.jar -- to launch options

📖 Full Installation Guide - Security warnings, manual installation, policy modes

📖 Uninstall Guide - Remove launch options, installed files, and optional config data

 For Modders

1. Add require=\ZombieBuddy, javaJarFile, and javaPkgName to your mod.info
2. Create patches using @Patch annotations
3. Build your JAR and place it in media/java/

📖 Modding Guide - Complete guide to creating Java mods

 Documentation

| Document | Description |
|----------|-------------|
| Installation Guide | End-user installation, security, and policy configuration |
| Uninstall Guide | Removing ZombieBuddy and optional config data |
| Command-Line Parameters | All agent parameters: verbosity, policy, experimental, etc. |
| Modding Guide | Creating patches, Lua exposure, mod signing, examples |
| Mod Signing | What signatures prove, what they do not prove, and how author trust works |
| Lua API Reference | Events, Watches, and Java mod status APIs |
| Dev/Debug Functions | Lua utilities: zbinspect, zbmethods, zbgrep, zbmap, etc. |

 Example: Creating a Patch

java
import me.zed_0xff.zombie_buddy.annotations.Patc

Top issues

Latest release

Windows Installer 4.4 windows_installer_4.4 2026-10-20
What's Changed
 Fix Project Zomboid discovery across Steam libraries by @Loukious in https://github.com/zed-0xff/ZombieBuddy/pull/79

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON