Chaos Mod

A single-player chaos mod for Project Zomboid Build 42.

The mod adds a random effect system to the game. Every 45 seconds, a new effect is activated. Effects can be helpful, harmful, or just completely random.

The mod currently includes 450+ effects, such as:

• Spawn a Zombie Nearby
• Give Random Tool
• Enable Rain

You can see the the full list of effects in Chaos Mod Hub or Google Sheets.

Chaos Mod also supports Twitch and YouTube integration. Viewers can vote for the next effect, and their nicknames can be displayed above zombies.

Installation

Method 1 — Steam Workshop

1. Set Project Zomboid to the unstable branch in Steam.
2. Download the mod from the Steam Workshop.
3. Enable the mod in the game.

Method 2 — Manual Installation (Skip this unless you really need it)

1. Set Project Zomboid to the unstable branch in Steam.

2. Download the latest release from GitHub.

3. Extract the ChaosModPZ folder to:

   %UserProfile%/Zomboid/Workshop

   The final path should look like this:

   C:\Users\YourUsername\Zomboid\Workshop\ChaosModPZ

---

Important

This mod requires the unstable branch of Project Zomboid on Steam.
It has been tested on version 42.18.0.

To enable the unstable branch, open Project Zomboid properties in Steam, go to Game Versions & Betas, and select the unstable branch.

---

Streaming Services Support

Chaos Mod supports Twitch and YouTube live chat integration. Both platforms work the same way through a separate application called StreamerApp, which handles the connection between the streaming service and the mod.

With streaming support enabled:

• Viewers can vote for the next effect.
• Viewer nicknames can appear above zombies.
• Voting options can be displayed in OBS.

To vote, viewers send the option number in chat:

<number>

For example:

2

Both <number> and !vote <number> formats are supported. The option numbers are displayed in OBS.

StreamerApp Installation

1. Install the mod first.
2. Download the latest release from Chaos Mod Hub or GitHub.
3. Extract ZomboidStreamerApp.exe to any folder and launch it.
4. Wait until the dashboard opens in your browser or open it manually: Local Dashboard
5. Connect Twitch and/or YouTube in the dashboard (see sub-sections below).

Twitch

In the StreamerApp dashboard, click the Login button in the Twitch card and complete the login process in your browser.

YouTube

YouTube integration uses your own YouTube Data API v3 key. The mod never logs in to your Google account.

In the StreamerApp dashboard, click Connect on the YouTube card. The Connect YouTube window includes a built-in step-by-step setup guide that walks you through creating an API key in Google Cloud Console. Once you have the key:

1. Paste your API key into the field below the guide.
2. Paste your current YouTube live video URL on the YouTube card.

Notes:

• YouTube does not support donation-triggered effects.
• Reading YouTube live chat consumes your API key's daily quota.

OBS Setup

To display voting options in OBS, add a browser source. Instructions for setting up the browser source are available in the StreamerApp dashboard.

Donation Effect Support

Chaos Mod supports donation-triggered effects.

This feature uses the same StreamerApp that is used for streaming services support.

Currently supported donation services:

• Twitch Bits
• Twitch Channel Points Rewards
• Twitch Subs
• DonationAlerts

Viewers can activate effects by donating a specific amount of money, or by cheering with Bits on Twitch, and including an effect ID in the donation message.

To activate a specific effect, they only need to include the effect ID number in the message.

Example donation messages:

50

or

Some message! 51

You can find effect IDs on Chaos Mod Hub, or create your own config there.

Note: Twitch subscriptions do not activate effects by ID. Instead, they activate a random effect every N subscriptions.

Twitch Bits Setup

You can enable Twitch Bits in the StreamerApp dashboard. You must be logged in to Twitch first.

Viewers cheer with bits and include an effect ID in the cheer message — the same tag formats as above are supported.

The amount of bits required to activate an effect is calculated from the effect's price group price multiplied by the Twitch Bits multiplier (configured in the dashboard, default is 100). For example, an effect with price 2 and multiplier 100 requires at least 200 bits.

Twitch Channel Points Rewards Setup

You can enable Twitch Bits in the StreamerApp dashboard. You can create rewards for each Tier of Price group of effects.

Twitch Subs Setup

You can enable Twitch Subs in the StreamerApp dashboard.

Note: Twitch subscriptions do not activate effects by ID. Instead, they activate a random effect every N subscriptions.

DonationAlerts Setup

You can set up DonationAlerts in the StreamerApp dashboard.

Donation Prices Export

Use "Export To Hub" in component to get unique URL for all your settings. You can share that link.

Excel export (legacy)

You can export donation prices to a XLSX file on StreamerApp dashboard. The XLSX includes a Price column when DonationAlerts is enabled and a Twitch Bits column when Twitch Bits is enabled.

The exported XLSX file can be imported into Google Sheets and shared with viewers as a donation price table.

The id column in the XLSX is an integer starting from 1. The same numeric ID is also returned by the local /mod/effects endpoint.

Editing Donation Prices

Donation prices are configured in StreamerApp dashboard.

Adding Other Donation Services — For Developers

Note

This section is for developers.

You can add support for other donation services by creating your own application that communicates with the local StreamerApp API.

To get effect prices, send a GET request to:

http://127.0.0.1:3959/mod/effects

Each effect entry includes:

• id — numeric ID starting from 1
• effect_id — internal string effect ID such as spawn_zombies_nearby
• price_result — resolved donation price for that effect

To activate an effect, send a request to:

http://127.0.0.1:3959/mod/activate-effect?effect=effect_id&nickname=nickname

The effect query parameter accepts either the numeric id or the string effect_id.

Example:

http://127.0.0.1:3959/mod/activate-effect?effect=spawn_zombies_nearby&nickname=ViewerName

or:

http://127.0.0.1:3959/mod/activate-effect?effect=17&nickname=ViewerName

Configuration

You can edit the mod configuration in StreamerApp dashboard or using button with gear icon in game (bottom-left corner).

Raw config file location:

%UserProfile%\Zomboid\Lua\ChaosMod\config.json

Effects Configuration

You can edit settings for each effect in StreamerApp dashboard or using button with gear icon in game (bottom-left corner).

Raw effects file location:

%UserProfile%\Zomboid\Lua\ChaosMod\effects.json

Languages

Chaos Mod supports multiple languages.

You can change the language in StreamerApp dashboard or using button with gear icon in game (bottom-left corner).

Supported languages:

• English (en)
• French (fr)
• German (de)
• Spanish (es)
• Portuguese (pt)
• Russian (ru)
• Polish (pl)
• Turkish (tr)
• Simplified Chinese (zh)
• Korean (ko)
• Japanese (ja)

FAQ

Mod does not work. What should I do?

Make sure you are using the unstable branch of Project Zomboid on Steam.

I want to use only donation effects, without random effects every 45 seconds and without voting. How can I do this?

In StreamerApp dashboard set these settings:

• Effects interval enabled: false
• Streamer mode enabled: true
• Voting enabled: false
• Donations enabled: true

I only want to display Twitch or YouTube nicknames above zombies, without random effects every 45 seconds and without voting. How can I do this?

In StreamerApp dashboard set these settings:

• Effects interval enabled: false
• Streamer mode enabled: true
• Voting enabled: false
• Donations enabled: false
• Use zombie nicknames: true

I use OBS Studio on a different PC. How can I use StreamerApp?

In StreamerApp dashboard set this setting:

• Bind to localhost only: false

StreamerApp OBS section now should display correct URL. If that URL does not work, restart the StreamerApp.

Is multiplayer supported?

No. Chaos Mod is designed for single-player only.

Development

To start make edits in Lua, you will need to install EmmyLua and Project Zomboid Umbrella. After installing Umbrella, set environment variable PZ_UMBRELLA to the path of the Umbrella folder.

How to compile ZomboidStreamerApp.exe by yourself

This is not required if you use precompiled ZomboidStreamerApp.exe from releases.

1. Install Bun: bun.com
2. Use command bun build --compile --minify index.ts --outfile dist/ZomboidStreamerApp.exe in StreamerMode folder

Disclaimer

This mod uses the json.lua library.

Copyright (c) rxi

Licensed under the MIT License.

Special Thanks

Chaos Mod uses the ChaosNPC system, which was inspired by the Bandits NPC mod.