A mod is a folder of files the game reads at startup: scripts that define items and recipes, Lua code that adds behavior, textures, 3D models, sounds and translations. Project Zomboid is built so that almost everything can be modified, which is why it has one of the biggest modding communities around.
How to install a mod (as a player)
- Open the mod's page on the Steam Workshop and hit Subscribe. Steam downloads it for you.
- Launch the game and go to Mods in the main menu.
- Enable the mod. If your save already exists, you can also enable it when loading, under More options → Mods.
- Read the mod's page: some mods need a new game, and others depend on another mod.
Where the files live
The game keeps all your stuff in a folder called Zomboid, inside your user folder:
| System | Folder |
|---|---|
| Windows | C:\Users\<your username>\Zomboid\ |
| macOS | /Users/<your username>/Zomboid/ |
| Linux | ~/Zomboid/ |
Inside it there are three things you'll use a lot when making mods:
Workshop/: this is where your mods in development go. The game loads them from here, and you upload them to Steam from here.console.txt: the game log. When something breaks, the error gets written here.Logs/: more complete logs, one per session.
The pieces of a mod
| Piece | What it's for | Format |
|---|---|---|
| Scripts | Defining items, recipes, models, repairs | .txt with PZ's own syntax |
| Lua | Adding behavior: loot, events, menus, actions | .lua |
| Textures and icons | How everything looks | .png |
| 3D models | Objects on the ground, in hand or worn | .x or .fbx |
| Translations | Names and text in each language | .json (since B42) |
| Sounds | Custom sound effects | .wav / .ogg |
You don't need all of them. A simple food mod uses just one script, one icon, one translation and a bit of Lua for the loot. That's exactly what we build in Your first mod.
What you need to get started
- Project Zomboid (Build 42).
- A text editor that isn't Notepad. VS Code is free and highlights Lua errors.
- An image editor for icons: GIMP, Krita, Aseprite or whatever you use.
- Optional: Blender, if you're going to make your own 3D models.
Debug mode: your best friend
To test mods, launch the game with the -debug option. On Steam: right-click Project Zomboid → Properties → Launch Options → type -debug.
That adds a debug menu inside the game, with things like:
- Items List: search for your item and add it to your inventory without having to find it.
- Reloading Lua files without restarting the game.
- Seeing errors on screen as soon as they happen.
Next step: Your first mod, step by step.