ZombieBuddy

https://github.com/zed-0xff/zombiebuddy
Admin
A powerful framework for Project Zomboid modders that enables Java bytecode manipulation and runtime...
Tokens:13,308
Snippets:186
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Installation Paths

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

Paths for manual installation of ZombieBuddy files on Windows.

```plaintext
C:\Program Files (x86)\Steam\steamapps\workshop\content\108600\3619862853\mods\ZombieBuddy\libs\
```

```plaintext
C:\Program Files (x86)\Steam\steamapps\common\ProjectZomboid\
```

--------------------------------

### Java Mod Policy Examples

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

Examples of setting the Java Mod Policy via Steam launch options.

```bash
-agentlib:zbNative=policy=deny-new --            (Windows)
```

```bash
-javaagent:ZombieBuddy.jar=policy=deny-new --    (macOS / Linux)
```

--------------------------------

### Windows Manual Installation Launch Option

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

Add this launch option to Project Zomboid's Steam properties for manual installation on Windows.

```bash
-agentlib:zbNative --
```

--------------------------------

### macOS/Linux Manual Installation JVM Argument

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

Add this JVM argument to Project Zomboid's Steam launch options for manual installation on macOS and Linux.

```bash
-javaagent:ZombieBuddy.jar --
```

--------------------------------

### Signing Task Output

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Example output showing the signature string to add to your Steam profile.

```text
> Task :signJarZBS
Add to Steam profile: JavaModZBS:cafebabe0123456789abcdef0123456789abcdef0123456789abcdef01234567

BUILD SUCCESSFUL in 1s
```

--------------------------------

### Debug Mode Launch Options

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

How to start Project Zomboid in debug mode using ZombieBuddy.

```bash
-agentlib:zbNative -- -debug
```

```bash
-javaagent:ZombieBuddy.jar -- -debug
```

--------------------------------

### Combining Windows Agent Parameters

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Use comma-separated values to set multiple parameters for the Windows agent. This example sets the verbosity level.

```bash
-agentlib:zbNative=verbosity=2,experimental --
```

--------------------------------

### Import JVM System Properties as Agent Arguments

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Reads JVM system properties prefixed with 'zb.' and uses them as ZombieBuddy agent arguments. This example imports verbosity and policy.

```bash
-Dzb.verbosity=2 -Dzb.policy=deny-new -javaagent:ZombieBuddy.jar=prop_prefix=zb --
```

```bash
-javaagent:ZombieBuddy.jar=verbosity=2,policy=deny-new --
```

--------------------------------

### ZombieBuddy.getClosureInfo(obj)

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Gets detailed metadata for a Lua closure.

```APIDOC
## ZombieBuddy.getClosureInfo(obj)

### Description
Gets metadata for a Lua closure, including file, name, parameters, and line number.

### Method
Lua

### Parameters
- **obj** (closure) - The Lua closure object.

### Response
#### Success Response
- **info** (table | nil) - A table containing closure metadata (file, filename, name, numParams, isVararg, line, fileLastModified), or nil if the object is not a closure.
```

--------------------------------

### Create a Java Patch with ZombieBuddy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/README.md

Example of how to create a Java patch using ZombieBuddy annotations. This snippet demonstrates patching a specific method within a game class.

```java
import me.zed_0xff.zombie_buddy.annotations.Patch;

@Patch(className = "zombie.SomeGameClass", methodName = "someMethod")
public static class MyPatch {
    @Patch.OnEnter
    public static void enter() {
        System.out.println("Method called!");
    }
}
```

--------------------------------

### Combining Java Agent Parameters

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Use comma-separated values to set multiple parameters for the Java agent. This example sets verbosity, policy, and allows unsigned modifications.

```bash
-javaagent:ZombieBuddy.jar=verbosity=1,policy=deny-new,allow_unsigned_mods=false --
```

--------------------------------

### Example authors.json structure

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModSigning.md

This JSON structure defines a list of known authors, including their SteamID64, a display name, and their public signing keys. This file is used by ZombieBuddy to map stable author identities to human-readable names and associated keys.

```json
[
  {
    "id": 76561198012345678,
    "name": "Author name",
    "keys": ["64 hex public key"]
  }
]
```

--------------------------------

### ZombieBuddy.getCallableInfo(obj)

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Gets metadata for Lua closures and Java callables.

```APIDOC
## ZombieBuddy.getCallableInfo(obj)

### Description
Retrieves metadata for Lua closures and Java callables, including invokers for exposed Java methods. This is equivalent to `zbmethod(obj)`.

### Method
Lua

### Parameters
- **obj** (callable) - The Lua closure or Java callable object.

### Response
#### Success Response
- **info** (table) - Metadata for the callable object.
```

--------------------------------

### ZombieBuddy.getClosureFilename(obj)

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Gets the filename of a Lua closure.

```APIDOC
## ZombieBuddy.getClosureFilename(obj)

### Description
Gets the filename of a Lua closure.

### Method
Lua

### Parameters
- **obj** (closure) - The Lua closure object.

### Response
#### Success Response
- **filename** (string | nil) - The filename of the closure, or nil if not available.
```

--------------------------------

### Generate Ed25519 Private Key

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

One-time setup to generate a cryptographic key for mod signing.

```bash
openssl genpkey -algorithm ed25519 -outform DER -out ~/.signing/ed25519-private.der
```

--------------------------------

### Get ZombieBuddy Version Information

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Retrieve the version string of the ZombieBuddy mod. getFullVersionString provides a more descriptive version string.

```lua
ZombieBuddy.getVersion()
ZombieBuddy.getFullVersionString()
```

--------------------------------

### Get All Events and Callbacks

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Retrieve all registered game events and their associated callbacks, or fetch callbacks for a specific event by name or directly via the event name index.

```lua
-- Get all events
local all = ZombieBuddy.Events.getAll()

-- Get callbacks for a specific event
local callbacks = ZombieBuddy.Events.getByName("OnCreatePlayer")
-- Or equivalently (via __index):
local callbacks = ZombieBuddy.Events.OnCreatePlayer
```

--------------------------------

### Get Events by File and Inspect Callback Info

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Fetch events and callbacks originating from a specific Lua file and retrieve detailed information about a callback, such as its source filename and line number.

```lua
-- Get events/callbacks from a specific file
local byFile = ZombieBuddy.Events.getByFile("/path/to/SomeMod.lua")
-- byFile.OnFillWorldObjectContextMenu[1] is the first callback from that file

-- Inspect a callback's source
local info = ZombieBuddy.getClosureInfo(callbacks[1])
print(info.filename, info.line)  -- e.g. "media/lua/client/SomeMod.lua", 42
```

--------------------------------

### Get Callable Information

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Retrieves metadata for a Lua function or Java-exposed method. For Java methods, it provides details about invokers and overloads.

```lua
zbmethod(obj)
```

--------------------------------

### Get Lua Closure and Callable Information

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Obtain detailed metadata for Lua closures, including file, line number, and function name. getCallableInfo provides similar information for both Lua closures and Java callables.

```lua
ZombieBuddy.getClosureInfo(obj)
ZombieBuddy.getCallableInfo(obj)
```

--------------------------------

### Load Additional Patch JARs

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Loads additional patch JARs at startup. Format is 'path:package_name', with multiple entries separated by semicolons.

```bash
-javaagent:ZombieBuddy.jar=patches_jar=/path/to/MyPatches.jar:com.example.patches --
```

```bash
-javaagent:ZombieBuddy.jar=patches_jar=/path/to/First.jar:com.first;/path/to/Second.jar:com.second --
```

--------------------------------

### Configure Gradle Credentials

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Add Steam ID and private key path to your global Gradle properties.

```properties
zbsSteamID64=76561198012345678
zbsPrivateKeyFile=/Users/you/.signing/ed25519-private.der
```

--------------------------------

### Define Main Initialization Class

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Implement an optional Main class to execute code upon mod loading.

```java
package com.yourname.yourmod;

public class Main {
    public static void main(String[] args) {
        System.out.println("[YourMod] Initializing...");
        // Your initialization code here
    }
}
```

--------------------------------

### Configure Gradle Plugin

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Include the plugin in settings and apply it in the build script.

```groovy
includeBuild '/path/to/zb-gradle-plugin'
// Or after the plugin is published to Gradle Plugin Portal:
// (no includeBuild needed)
```

```groovy
plugins {
    id 'java'
    id 'io.github.zed-0xff.zb-gradle-plugin' version '1.0.0'
}

zbSigning {
    jarTask = 'jar'  // or 'shadowJar' for fat JARs
}
```

--------------------------------

### Build and Sign Mod

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Execute the build task to generate the JAR and its corresponding signature file.

```bash
gradle build
```

--------------------------------

### macOS and Linux Launch Options for ZombieBuddy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Installation.md

Configure these launch options in Steam for macOS and Linux to enable ZombieBuddy as a Java agent. The `--` at the end is mandatory.

```bash
-javaagent:ZombieBuddy.jar --
```

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

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

--------------------------------

### Windows Launch Options for ZombieBuddy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Installation.md

Configure these launch options in Steam for Windows to enable ZombieBuddy using the native library. The `--` at the end is mandatory. `zbNative.dll` automatically loads `ZombieBuddy.jar`.

```bash
-agentlib:zbNative --
```

```bash
-agentlib:zbNative=verbosity=1 --
```

```bash
-agentlib:zbNative=verbosity=2 --
```

--------------------------------

### Expose Classes to Lua

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Exposes Java classes to Lua at startup. Provide a comma-separated list of fully-qualified class names.

```bash
-javaagent:ZombieBuddy.jar=expose_classes=com.example.MyClass,com.example.OtherClass --
```

--------------------------------

### Configure mod.info File

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Required configuration entries for the mod.info file to enable ZombieBuddy integration.

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

--------------------------------

### Windows Alternate Launch Option

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/steam.txt

Set the _JAVA_OPTIONS line for Project Zomboid's Alternate Launch on Windows.

```bash
SET _JAVA_OPTIONS=-agentlib:zbNative
```

--------------------------------

### Windows Java Agent Configuration

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Use this format to configure ZombieBuddy with command-line parameters on Windows systems. The '-agentlib' flag is used, and parameters are comma-separated. The '--' terminator is mandatory.

```bash
-agentlib:zbNative=param1=value1,param2=value2 --
```

--------------------------------

### Windows Launch Option for Deny-New Policy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Installation.md

Use this command-line argument on Windows to launch ZombieBuddy with the 'deny-new' policy, which silently skips any JAR that isn't already approved.

```bash
-agentlib:zbNative=policy=deny-new --
```

--------------------------------

### Select Console Frontend

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Selects the UI for Java mod approval dialogs. 'console' uses stdin/stdout for headless mode.

```bash
-javaagent:ZombieBuddy.jar=frontend=console --
```

--------------------------------

### Build and Deploy Mod

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Commands to compile the project and move the resulting JAR to the local Zomboid mods directory.

```bash
gradle build
cp build/libs/YourMod.jar ~/Zomboid/mods/YourMod/[version]/media/java/
```

--------------------------------

### Enable Experimental Mode for ZombieBuddy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

ZombieBuddy must be loaded with experimental mode enabled. The command line arguments differ for macOS/Linux and Windows.

```bash
-javaagent:ZombieBuddy.jar=experimental --
```

```bash
-agentlib:zbNative=experimental --
```

--------------------------------

### Set Custom Configuration Directory

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Specifies the directory for ZombieBuddy configuration and cache files.

```bash
-javaagent:ZombieBuddy.jar=config_dir=/path/to/zombie_buddy_config --
```

--------------------------------

### macOS/Linux Java Agent Configuration

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Use this format to configure ZombieBuddy with command-line parameters on macOS and Linux systems. Ensure the '-javaagent' flag points to the ZombieBuddy JAR and parameters are comma-separated.

```bash
-javaagent:ZombieBuddy.jar=param1=value1,param2=value2 --
```

--------------------------------

### Configure Gradle Dependencies

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Add the ZombieBuddy API and Project Zomboid classes as compile-only dependencies to your Gradle project.

```gradle
dependencies {
    // ZombieBuddy API (compile-only, provided at runtime)
    compileOnly files("path/to/ZombieBuddy.jar")
    
    // Project Zomboid classes (compile-only)
    compileOnly files("path/to/ProjectZomboid/Contents/Java")
}
```

--------------------------------

### ZombieBuddy.getFullVersionString()

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Retrieves the full version string, including the mod name.

```APIDOC
## ZombieBuddy.getFullVersionString()

### Description
Retrieves the full version string, e.g., "ZombieBuddy v1.0".

### Method
Lua

### Parameters
None

### Response
#### Success Response
- **fullVersion** (string) - The full mod version string.
```

--------------------------------

### macOS/Linux Launch Option for Deny-New Policy

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Installation.md

Use this command-line argument on macOS or Linux to launch ZombieBuddy with the 'deny-new' policy, which silently skips any JAR that isn't already approved.

```bash
-javaagent:ZombieBuddy.jar=policy=deny-new --
```

--------------------------------

### ZombieBuddy Core Methods

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

General-purpose methods available on the `ZombieBuddy` global for version checking and inspecting Lua closures/callables.

```APIDOC
## ZombieBuddy Core Methods

General-purpose methods available on the `ZombieBuddy` global.

### Methods

- `getVersion()`: Returns the mod version string.
- `getFullVersionString()`: Returns e.g. `"ZombieBuddy v1.0"`.
- `getClosureFilename(obj)`: Filename of a Lua closure, or nil.
- `getClosureInfo(obj)`: Table with `file`, `filename`, `name`, `numParams`, `isVararg`, `line`, `fileLastModified` for a Lua closure; nil otherwise.
- `getCallableInfo(obj)`: Same as `zbmethod(obj)`: metadata for Lua closures and Java callables.
```

--------------------------------

### Mod Directory Structure

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Recommended file layout for including source code within a mod distribution.

```text
YourMod/
├── [version]/
│   ├── mod.info
│   ├── media/
│   │   └── java/
│   │       └── YourMod.jar
│   └── src/              # Optional: include source code
│       └── com/
│           └── yourname/
│               └── yourmod/
└── common/
```

--------------------------------

### Exit After Game Initialization

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Exits the game immediately after initialization completes. Useful for testing or CI pipelines. This is a flag parameter.

```bash
-javaagent:ZombieBuddy.jar=exit_after_game_init --
```

--------------------------------

### Configure Preload Manifest Attribute

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Set the ZB-Preload attribute in the JAR manifest to enable early loading.

```text
ZB-Preload: true
```

```gradle
jar {
    manifest {
        attributes(
            'ZB-Preload': 'true'
        )
    }
}
```

```gradle
shadowJar {
    manifest {
        attributes(
            'ZB-Preload': 'true'
        )
    }
}
```

--------------------------------

### Bind Parameters in Advice Methods

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Use parameter annotations like @Patch.This, @Patch.Argument, and @Patch.Return to access context from the intercepted method.

```java
@Patch(className = "zombie.characters.IsoGameCharacter", methodName = "attack")
public class AttackPatch {
    @Patch.OnEnter
    public static void enter(@Patch.This Object self,
                             @Patch.Argument(0) Object target,
                             @Patch.AllArguments Object[] args) { }

    @Patch.OnExit
    public static void exit(@Patch.Return(readOnly = false) int result,
                            @Patch.Thrown Throwable thrown) {
        if (thrown == null) result = result * 2;
    }
}
```

--------------------------------

### Enable Experimental Patches

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Enables experimental patches. This is a flag parameter and does not require a value.

```bash
-javaagent:ZombieBuddy.jar=experimental --
```

--------------------------------

### ZombieBuddy.getVersion()

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Retrieves the version string of the mod.

```APIDOC
## ZombieBuddy.getVersion()

### Description
Retrieves the version string of the mod.

### Method
Lua

### Parameters
None

### Response
#### Success Response
- **version** (string) - The mod version string.
```

--------------------------------

### Manually Exposing Classes to Lua

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Use the Exposer utility class to register a class with the Lua engine at runtime.

```java
import me.zed_0xff.zombie_buddy.Exposer;

// In your initialization code
Exposer.exposeClass(MyCustomClass.class);
```

--------------------------------

### ZombieBuddy.Watches

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Experimental APIs for hooking Java methods to log their calls and arguments. Allows adding, removing, and clearing watches.

```APIDOC
## ZombieBuddy.Watches (Experimental)

Hook any Java method and log its calls and arguments.

### Methods

- `Add(className, methodName)`: Add a watch. Every call to the method is logged with its arguments.
- `Remove(className, methodName)`: Remove a watch.
- `Clear()`: Remove all watches.

### Examples

```lua
-- Watch a game method
ZombieBuddy.Watches.Add("zombie.iso.IsoPlayer", "addBlood")
ZombieBuddy.Watches.Add("zombie.Lua.LuaManager", "RunLua")

-- Logs appear in the game console: [ZB Watch] zombie.iso.IsoPlayer.addBlood(...)

-- Remove when done
ZombieBuddy.Watches.Remove("zombie.iso.IsoPlayer", "addBlood")
ZombieBuddy.Watches.Clear()
```

> **Note**: The class must be loaded for the watch to apply. If the class is not yet loaded, the watch is registered and will apply on first load.
```

--------------------------------

### Inspect Java Object Methods

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Returns a sorted list of method signature strings for a given object. Use `includePrivate` to include private and inherited methods.

```lua
zbmethods(obj)
zbmethods(obj, true)
```

--------------------------------

### Define Mod Directory Structure

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Standard directory layout for a Project Zomboid mod utilizing ZombieBuddy.

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

--------------------------------

### zbgreplog

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Searches the game console log file for lines containing a specific substring.

```APIDOC
### `zbgreplog(substring)`

Reads the game console log file and returns a 1-based table of **lines** that contain `substring`. Returns nil if the file cannot be read or substring is null/empty.
```

--------------------------------

### zbget, zbset, zbcall

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Functions for accessing, modifying, and invoking properties or methods on objects. `zbget` retrieves a field/property, `zbset` sets it, and `zbcall` invokes a method.

```APIDOC
## zbget, zbset, zbcall

### Description
Functions for interacting with object properties and methods.

### `zbget(obj, name)` / `zbget(obj, name, defaultValue)`
Gets the field or property `name` on `obj`. Returns `defaultValue` (or nil) if missing/inaccessible.

### `zbset(obj, name, value)`
Sets the field or property `name` on `obj` to `value`. Returns boolean success.

### `zbcall(obj, methodName, ...)`
Calls the method `methodName` on `obj` with the given arguments. Returns the method’s return value. Uses reflection (e.g. for calling Java methods by string name from Lua).
```

--------------------------------

### @LuaMethod

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Exposes a static Java method as a global function in the Lua environment.

```APIDOC
## @LuaMethod

### Description
Annotate a static method with @LuaMethod to expose it as a global function in Lua.

### Attributes
- **name** (string) - Required - The name of the function as it will appear in Lua.
- **global** (boolean) - Required - Must be set to true to register as a global function.
```

--------------------------------

### .zbs File Structure

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModSigning.md

The structure of the .zbs sidecar file, which is stored alongside the mod's JAR file. It contains the signature information.

```text
ZBS
SteamID64:<author steam id>
Signature:<ed25519 signature hex>
```

--------------------------------

### @Exposer.LuaClass

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Registers a Java class with the game's Lua engine for script access.

```APIDOC
## @Exposer.LuaClass

### Description
Annotate a class with @Exposer.LuaClass to have the loader discover and register it with the game's Lua engine.
```

--------------------------------

### Disable Unsigned Mod Loading

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

When set to 'false', mods without ZBS signatures are treated as invalid unless 'policy=allow-all'.

```bash
-javaagent:ZombieBuddy.jar=allow_unsigned_mods=false --
```

--------------------------------

### Exposer.exposeClass

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Manually exposes a Java class to the Lua engine at runtime.

```APIDOC
## Exposer.exposeClass(Class<?> clazz)

### Description
Manually registers a class with the Lua engine during runtime initialization.

### Parameters
- **clazz** (Class) - Required - The class to be exposed to Lua.
```

--------------------------------

### ZombieBuddy.Events

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

APIs for inspecting game event hooks registered by Lua code. Allows retrieval of all events, events by name, events by file, and direct access to event callbacks by name.

```APIDOC
## ZombieBuddy.Events

Inspect game event hooks registered by Lua code.

### Methods

- `getAll()`: Returns a table mapping event names to their callback lists.
- `getByName(eventName)`: Returns the list of callbacks for the given event (e.g. `"OnCreatePlayer"`).
- `getByFile(filename)`: Returns a table of events that have callbacks from the given Lua file. Each event name maps to a 1-based array of those callbacks.
- `EventName` (index): Access event callbacks by name: `ZombieBuddy.Events.OnCreatePlayer` returns the same as `getByName("OnCreatePlayer")`.

### Related helpers on ZombieBuddy

- `getClosureFilename(closure)`: Returns the source filename for a callback (LuaClosure).
- `getClosureInfo(closure)`: Returns a table with `file`, `filename`, `name`, and `line` for a callback.

### Examples

```lua
-- Get all events
local all = ZombieBuddy.Events.getAll()

-- Get callbacks for a specific event
local callbacks = ZombieBuddy.Events.getByName("OnCreatePlayer")
-- Or equivalently (via __index):
local callbacks = ZombieBuddy.Events.OnCreatePlayer

-- Get events/callbacks from a specific file
local byFile = ZombieBuddy.Events.getByFile("/path/to/SomeMod.lua")
-- byFile.OnFillWorldObjectContextMenu[1] is the first callback from that file

-- Inspect a callback's source
local info = ZombieBuddy.getClosureInfo(callbacks[1])
print(info.filename, info.line)  -- e.g. "media/lua/client/SomeMod.lua", 42
```
```

--------------------------------

### Skip Original Method Execution

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Set skipOn = true in @Patch.OnEnter and return true from the advice method to prevent the original method from running.

```java
@Patch(className = "zombie.SomeClass", methodName = "someMethod")
public class SkipExample {
    @Patch.OnEnter(skipOn = true)
    public static boolean enter() {
        if (shouldSkip) {
            return true; // Original method will NOT be executed
        }
        return false; // Original method will proceed normally
    }
}
```

--------------------------------

### zbkeys, zbvalues

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Helper functions to retrieve keys and values from tables or maps.

```APIDOC
## Table/collection helpers

### `zbkeys(obj)`
Returns a 1-based array of keys. Supports `KahluaTable` and Java `Map`.

### `zbvalues(obj)`
Returns a 1-based array of values. Supports `KahluaTable` and Java `Map`.
```

--------------------------------

### Inspect Java Object Details

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Returns a descriptive table for an object, including its type, element types (for collections), fields, and methods. Set `includePrivate` to true to include private and inherited members.

```lua
zbinspect(obj)
zbinspect(obj, true)
```

--------------------------------

### Exposing Classes to Lua via Annotations

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Annotate a class with @Exposer.LuaClass to register it with the Lua engine, or use @LuaMethod for static global functions.

```java
import me.zed_0xff.zombie_buddy.Exposer;

@Exposer.LuaClass
public class MyLuaApi {
    public String greet(String who) {
        return "Hello, " + who;
    }
}
```

```java
import se.krka.kahlua.integration.annotations.LuaMethod;

public class MyGlobals {
    @LuaMethod(name = "myGlobalFunc", global = true)
    public static String myGlobalFunc(String arg) {
        return "got: " + arg;
    }
}
```

--------------------------------

### Remove Windows Launch Option

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Uninstall.md

Remove the ZombieBuddy launch option from Project Zomboid properties in Steam on Windows.

```bash
-agentlib:zbNative ... --
```

--------------------------------

### Set HTTP Client Timeout

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Sets the timeout in seconds for HTTP connections and requests. Applies to all outbound HTTP calls.

```bash
-javaagent:ZombieBuddy.jar=http_client_timeout=30 --
```

--------------------------------

### Define a Basic Patch

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Use the @Patch annotation to target a class and method, with @Patch.OnEnter and @Patch.OnExit for interception.

```java
package com.yourname.yourmod.patches;

import me.zed_0xff.zombie_buddy.annotations.Patch;

@Patch(className = "zombie.SomeGameClass", methodName = "someMethod", warmUp = true)
public class MyPatch {
    @Patch.OnEnter
    public static void enter() {
        System.out.println("[YourMod] Intercepted method call!");
    }
    
    @Patch.OnExit
    public static void exit() {
        System.out.println("[YourMod] Method finished!");
    }
}
```

--------------------------------

### Set HTTP Cache TTL

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Sets the time-to-live in seconds for the in-memory HTTP response cache. '0' disables caching.

```bash
-javaagent:ZombieBuddy.jar=http_cache_ttl=0 --
```

--------------------------------

### Inspect Java Object Fields

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Retrieves a table of field names and their values for a given object. Use `includePrivate` to also inspect private and inherited fields.

```lua
zbfields(obj)
zbfields(obj, true)
```

--------------------------------

### Remove macOS/Linux Launch Option

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/Uninstall.md

Remove the ZombieBuddy launch option from Project Zomboid properties in Steam on macOS and Linux.

```bash
-javaagent:ZombieBuddy.jar ... --
```

--------------------------------

### @Patch.VarHandle

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Provides direct field access to private members without using reflection.

```APIDOC
## @Patch.VarHandle

### Description
Allows direct access to private fields of a target class. The annotation is applied to a static VarHandle field within a patch class.

### Attributes
- **value/name** (string) - Optional - Member name(s) to look up.
- **className** (string) - Optional - Fully qualified owner class.
- **owner** (class) - Optional - Type-safe class reference.
- **optional** (boolean) - Optional - If true, leaves the handle null if the member is missing.
- **type** (class) - Required - The type of the target field.
```

--------------------------------

### Add and Remove Java Method Watches

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Hook into Java methods to log their calls and arguments. Watches are applied when the class is loaded. Use Remove to stop watching a specific method or Clear to remove all watches.

```lua
-- Watch a game method
ZombieBuddy.Watches.Add("zombie.iso.IsoPlayer", "addBlood")
ZombieBuddy.Watches.Add("zombie.Lua.LuaManager", "RunLua")

-- Logs appear in the game console: [ZB Watch] zombie.iso.IsoPlayer.addBlood(...)

-- Remove when done
ZombieBuddy.Watches.Remove("zombie.iso.IsoPlayer", "addBlood")
ZombieBuddy.Watches.Clear()
```

--------------------------------

### Canonical Payload Format

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModSigning.md

The format for the canonical payload that is signed by the mod author. This payload includes the mod's SteamID64 and the JAR's SHA256 hash.

```text
ZBS:<SteamID64>:<JAR_SHA256>
```

--------------------------------

### Java Mod Status

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

APIs to query the current loader policy and per-mod load status of Java mods.

```APIDOC
## Java Mod Status

Query the current loader policy and per-mod load status. Useful for mods that display Java mod information (e.g. [ZBetterModList](https://github.com/zed-0xff/ZBetterModList)).

### Methods

- `ZombieBuddy.getPolicy()`: Returns the active policy as a string: `"prompt"`, `"deny-new"`, or `"allow-all"`.
- `ZombieBuddy.getJavaModStatus(modId)`: Returns a table for the given mod id, or `nil` if ZombieBuddy didn't consider a JAR for it.

### Status table fields

| Field       | Type    | Meaning |
|-------------|---------|---------|
| `loaded`    | boolean | `true` if the JAR was actually loaded this run. |
| `reason`    | string  | `"loaded"` or a short skip reason (e.g. `"blocked by policy=deny-new"`). |
| `sha256`    | string  | Hex SHA-256 of the JAR, or `nil` if there was no JAR. |
| `decision`  | string  | `"yes"`, `"no"`, or `nil` if no decision was recorded. |
| `persisted` | boolean | `true` if the decision came from the on-disk approvals file (vs session-only). |

### Example

```lua
local status = ZombieBuddy.getJavaModStatus("SomeJavaMod")
if status then
    if status.loaded then
        print("loaded, decision=" .. tostring(status.decision) .. ", persisted=" .. tostring(status.persisted))
    else
        print("blocked: " .. status.reason)
    end
end
```
```

--------------------------------

### zbmap

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Transforms a table or collection by applying a closure or method to each element.

```APIDOC
### `zbmap(obj, closure)`  
**or** `zbmap(obj, methodName)`

- **With Lua function `closure`:** For each (key, value) in table/map or (index, value) in list, calls `closure(key, value)` (or `closure(index, value)` for list). Return 0 values to skip, 1 to set `out[key] = value`, 2 to set `out[newKey] = newVal`. Builds and returns a new table.
- **With string `methodName`:** For each value, calls the no-arg Java method `methodName` on that value and uses the result (or original value if call fails). Works on `KahluaTable`, `Map`, `List`.
```

--------------------------------

### zbgrep

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/DevDebugFunctions.md

Filters entries from a table, collection, or inspected object based on a pattern or a predicate function.

```APIDOC
### `zbgrep(obj, pattern)` / `zbgrep(obj, pattern, caseSensitive)`  
**or** `zbgrep(obj, predicate)`

**String pattern:** Keeps entries where the key or value string contains `pattern`. For lists, matches the element’s string. Case-insensitive by default; use `zbgrep(obj, pattern, true)` for case-sensitive. For non-table/list/map objects, runs on `zbinspect(obj)` and greps `fields` and `methods`.

**Callable predicate:** Keeps entries where the predicate returns truthy (non-nil, not false).

- **Table / Map:** predicate is called with `(key, value)`.
- **List:** predicate is called with `(item)`.
- **Other:** same as pattern mode: greps inspected `fields` and `methods` using the predicate.

Returns a new table (or list-like table for lists) with only the matching entries.
```

--------------------------------

### Access Fields with @Patch.Field

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Bind parameters to class fields for reading or writing. You can provide multiple names for version-agnostic field resolution.

```java
@Patch(className = "zombie.characters.IsoPlayer", methodName = "update")
public class PlayerUpdatePatch {
    @Patch.OnEnter
    public static void enter(@Patch.This Object self,
                             @Patch.Field(readOnly = true) String username,      // read-only
                             @Patch.Field("maxSpeed") float speed,               // read/write (default)
                             @Patch.Field({"speedNew", "speed"}) float spd,      // tries "speedNew", falls back to "speed"
                             @Patch.Field int stamina) {                         // read/write (default)
        if (stamina < 10) stamina = 10;  // write-back happens after advice returns
    }
}
```

--------------------------------

### Query Java Mod Status

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/LuaAPI.md

Retrieve the loading status and decision details for a specific Java mod. This is useful for displaying Java mod information, such as in a mod list.

```lua
local status = ZombieBuddy.getJavaModStatus("SomeJavaMod")
if status then
    if status.loaded then
        print("loaded, decision=" .. tostring(status.decision) .. ", persisted=" .. tostring(status.persisted))
    else
        print("blocked: " .. status.reason)
    end
end
```

--------------------------------

### Set Verbosity Level

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/CommandLine.md

Controls the amount of logging output. Use values from -2 (errors only) to 2 (trace details).

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

--------------------------------

### Accessing Private Members with VarHandle

Source: https://github.com/zed-0xff/zombiebuddy/blob/master/doc/ModdingGuide.md

Use @Patch.VarHandle to access private fields directly without reflection. The field type must be specified via the type attribute.

```java
@Patch(className = "zombie.SomeClass", methodName = "someMethod")
public class SomePatch {
    @Patch.VarHandle(type = int.class)
    public static VarHandle privateCount;

    @Patch.OnEnter
    public static void enter(@Patch.This Object self) {
        int v = (int) privateCount.get(self);
    }
}
```
Tokens:
Raw