Modding

Navigation:

Community > Modding > Modding

Spiffo's Workshop is the home of Project Zomboid mods on Steam.

This page is being reworked. Please see the new page variant lower down, and make changes there

Terms & Conditions

By playing Project Zomboid, you agree to the: Terms and Conditions

In terms of the modding of PZ, you also agree with the: Modding Policy

Key restrictions

• The Indie Stone reserve the right to implement any features in the game irrespective of whether mods exist that accomplish the same goal.
• PZ modders are solely responsible for their mod, including (but not limited to compliance with any hosting platforms (such as Steam Workshop). They are also responsible for obtaining third party consents for any third party materials in the mod. Legally, we have to ask that modders to ‘represent and warrant’ (i.e. promise legally) that their mod is their own original work and any third party contents are fully and properly licensed by the modder.
• Creation of mods is subject to our modding policy, which may be updated from time to time with any technical requirements regarding how PZ mods must work.
• Project Zomboid modders are free to receive monetary/gift donations from the players who use their releases, and appreciate the time and effort put into them. However having mods created exclusively for those who choose to donate (or separate ‘in-mod’ content and bonuses) is not allowed. Mod creators cannot sell modifications to Project Zomboid.

How to install/play mods

Mod menu

To get a full tutorial on how to install mods, see RoboMat's tutorial on the forums.

To start a mod up, first make sure the mod is installed in the correct directory. Once you have done this, start up Project Zomboid. Once you get to the main menu, down at the bottom of the screen when you see "Survival" and "Sandbox" you will also find a menu option called Mods. Click on it, which will then lead you to the mod menu.

In there you should see the list of mods that you have installed. Double click on the mod you wish to start and a green tick should appear next to the mod. Next thing to do is shut down Project Zomboid and start it up again. Once started your mod should now be ready to go. Instructions on using the mod are usually contained in README's or information in the thread.

Current mods

• Spiffo's Workshop
• Completed mods
• Work-in-Progress mods

Modding tutorials

Tutorial	Author	Last updated
Project Zomboid Modding Guide (WIP)	Fenris Wolf	July 27, 2019
Lua Events (v41.65)	co`	March 4, 2024
RoboMat's Tutorials	RoboMat	July 24, 2013
Java Scripting Guide (very out of date, only the item and recipe sections seems to be applicable to current builds)	Lemmy101	July 24, 2013

A note regarding optimization and timestamps

This numerical information in the console.txt output log is a timestamp, such as in "LOG  : General , 1669904231941" If you need to evaluate the runtime impact of code it is a good metric.

A note regarding updating and/or changing mods

Removing .txt and .lua files from a mod before updating them to the steam workshop may result in file mismatch errors etc. on account of steam not automatically removing said files from clients and/or servers. One solution is manually deleting these files from the installation directories of the server and/or clients. As well modders can avoid this issue by keeping those files, instead of removing them, but editing those files so they are empty instead of having any functional content. Including commented text explaining the reason for this in the files is also a good practice.

A note regarding Macs, Linux and case sensitivity

Note that, unlike Windows, Mac and Linux OS are case-sensitive regarding file and directory names. Although people playing PZ on Linux is uncommon, it's far more common with server hosting services. To avoid issues, make sure and follow the vanilla PZ capitalization conventions for file and directory names.

For example: with clothing mods fileguidtable.xml works for Windows and Mac, but will cause serious issue for Linux as it will be looking for "fileGuidTable.xml", as that is how the vanilla PZ file is capitalized. Although Client, Server, and Shared will work for the lua directories for non-Linux systems. it won't work for Linux; consequently use the vanilla capitalization, "client", "server" and "shared" for those.

Javadoc reference to Project Zomboid codebase

• Project Zomboid Java documentation v41.78 (Unofficial)
• Project Zomboid Java documentation v41.77
• Project Zomboid Java documentation v41.65 (Unofficial)
• Project Zomboid Java documentation v40.43 (Unofficial)
• Project Zomboid Java documentation v39.67 (Unofficial)
• Project Zomboid Java documentation v38.30 (Unofficial)

Basic Lua language

• An Introduction to Lua
• Variables, Assignments and Datatypes
  • Test yourself solutions
• Arithmetic Operators
• Relational and Boolean Operators
• Concatentation and Length Operators
• [If Statements and Functions]]
• Loops
• Local and Global Variables
• Tables
• Looping Through Tables
• Lua Functions

Typescript modding

You can now use Typescript language to write your mods which are then compiled into lua. However it is not necessary to use Typescript to write mods.

• PipeWrench - Wiki
• PipeWrench - Typing
• PZPW - NodeJS Command-line Tool

Modding tools

• Decompiling & setting up auto-complete/intellisense in IDEA IntelliJ
• Notepad++, a simple editor.
• VS code, a simple editor.
• Free Online GUID Generator: for making GUIDs for modded clothing and outfits.

Important additional modding resources

• Setting up the mod.info file: a link to a post on TIS Discord explaining how.
• PZ Keycode references.
• Variables to use when creating an item.
• Guide for adding a new Skill/Perk, add XP and find all perks names.
• Guide for adding a custom trait.

General additional modding resources

• How To Create an Animation.
• Guide to make a hair mod.
• A YouTube playlist with Blackbeard's modding tutorials.
• Photoshop Masks used for making and editing tile sprites, a link to a post on TIS Discord with the file.
• Global Mod Data: How to use this powerful tool for tracking global mod data.
• Guide to make a custom Timed Action.
• A list of all the animation variables used in timed actions.
• A flow chart for the Timed Actions
• SpawnerAPI: Allows for pending the spawns of vehicles, items, zombies in order to spawn things anywhere in the world. Upon loading the cell in question the item becomes spawned in.
• Guide to how PZ loot distribution works on TIS Discord.
• Spawning a tile from it's name: a link to a post on TIS Discord explaining how.
• How to spawn loot on specific zombie outfit corpses: a link to a post on TIS Discord explaining how.
• Item spawning examples that work: a link to a post on TIS Discord explaining how.
• An archive with files demonstrating how to add modded sandbox options: a link to a post on TIS Discord.
• A tool for dumping distro table contents to console.txt: a lint to a post on TIS Discord with the code.
• How to use read/write with files in mods, useful for server ini files: a link to a post on TIS Discord explaining how.
• A post on TIS discord with code to serialize lua table into json and vice versa.
• A guide on how to change Zomboid's in-game music and sound effects.
• Looking for Error messages in the console log, a short guide on TIS Discord.
• Candle - EmmyLua Support for PZ's Java API.
• pzstorm/capsid - Project Zomboid mod development framework for Gradle. Apparently abandoned?
• WordZed tutorial on YouTube.
• Complete Vehicle Modding Tutorial on TIS forum.
• Useful links.
• Making New Tiles for PZ.
• How To Mod The Loot Distribution System.
• An up-to-date (41.78) reference to events and hooks.
• PZEventStubs: Lua stubs for events and hooks.
• A reference for adding custom sandbox options.

Clothing modding resources

• Guide for adding new clothing items with modding for build 41.
• A list of Blood Locations used for Clothing Modding; a post on TIS Discord.
• A list of Mask IDs used for Clothing Modding; a post on TIS Discord.
• A Graphic to explain the masking system for clothing in PZ; a post on TIS Discord.

Old and more specific additional modding resources

• isoRangeScan: This is an utility function meant for large scale scans of isoGridSquares around a given IsoObject. The scans are done fractally - that is to say from a center (or centers) outward to fill a larger area.
• ItemZed: for editing Item scripts and distribution files (out of date, needs to be updated to work properly with build 41)

Localization

If you plan to support other languages in your mod, you should save the text file using the proper encoding format that corresponds to the language you're translating. If you don't, characters will not appear correctly.

Language	Code	Encoding Format
Argentina Spanish	AR	Western (iso-8859-1)
Catalan	CA	Central European (ibm 852)
Chinese-Traditional	CH	UTF-8
Chinese-Simplified	CN	UTF-8
Czech	CS	Central European (ibm 852)
Danish	DA	Western (iso-8859-15)
German	DE	Western (iso-8859-1)
English	EN	UTF-8
Spanish	ES	Western (iso-8859-1)
Finnish	FI	UTF-8
French	FR	Western (iso-8859-1)
Hungarian	HU	Central European (iso-8859-2)
Indonesian	ID	UTF-8
Italian	IT	Western (iso-8859-1)
Japanese	JP	UTF-8
Korean	KO	UTF-8
Dutch	NL	Western (iso-8859-1)
Norwegian	NO	Western (iso-8859-15)
Filipino	PH	UTF-8
Polish	PL	Central European (windows-1250)
Portuguese	PT	Western (iso-8859-1)
Portuguese-Brazil	PTBR	Western (iso-8859-1)
Romanian	RO	UTF-8
Russian	RU	Cyrillic (windows-1251)
Thai	TH	UTF-8
Turkish	TR	Turkish (iso-8859-9)
Ukrainian	UA	Cyrillic (windows-1251)

Mapping tutorials

Main article: Mapping

Tutorial	Author	Last updated
The One Stop TileZed Mapping Shop	RingoD123	January 30, 2017
How to Combine Map Mods	RingoD123	June 11, 2017
Full list of current Room Definitions	RingoD123	February 7, 2014
Making new room definitions	RingoD123	June 10, 2017
Mapping Tutorial's and Videos	Thuztor	April 20, 2015
Mapping Tutorial's and Videos (Outdated)	Thuztor	September 12, 2017
VegMap to Testing Custom Map	Cpt_Paradox	January 28, 2017
Making rooms with the place wall tool, item spawns, ortho and more!	Cpt_Paradox	November 30, 2017
Sliding Glass Doors, New Textures, Here's How!	Cpt_Paradox	November 30, 2017
How to make a map Start to Finish Full Video Tutorial	BlackBeard	January 30, 2017
All player made Building Archives	BlackBeard	May 31, 2019
Custom texture packs and tile definitions	EasyPickins	June 5, 2014
Card's Tutorial for Terrain Generation	Cardenaglo	February 22, 2017
Video Tutorials mapping	Atoxwarrior	June 26, 2016

Mapping tools

• TileZed, WorldEd, and Tilesets (March 14, 2022)
• TileZed, WorldEd, and Tilesets (May 17, 2018)

File format

• File format documentation

Mapping resources

• PZ Tiles and a comprehensive selection of other mapping and tile making resources.
• The build 41 base and vegetation maps for PZ.
• The build 40 base and vegetation maps for PZ.
• An app for replacing the zombie layers on cells.
• An app for moving the cells in maps.
• A more recent base map for PZ.
• Making New Tiles for PZ.

New modding page, under construction

This section contains a rework of the modding page. Some extra information may be here.

This article is currently under construction.

It is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well.

If this page has not been updated in a while, please replace this notice with {{Improve}}. Last edit was 18/06/2023.

Navigation:

Modding > Modding

Spiffo's Workshop is the home of Project Zomboid mods on Steam.

Terms & Conditions

By playing Project Zomboid, you agree to the: Terms and Conditions

In terms of the modding of PZ, you also agree with the: Modding Policy

Key restrictions

• The Indie Stone reserve the right to implement any features in the game irrespective of whether mods exist that accomplish the same goal.
• PZ modders are solely responsible for their mod, including (but not limited to compliance with any hosting platforms (such as Steam Workshop). They are also responsible for obtaining third party consents for any third party materials in the mod. Legally, we have to ask that modders to ‘represent and warrant’ (i.e. promise legally) that their mod is their own original work and any third party contents are fully and properly licensed by the modder.
• Creation of mods is subject to our modding policy, which may be updated from time to time with any technical requirements regarding how PZ mods must work.
• Project Zomboid modders are free to receive monetary/gift donations from the players who use their releases, and appreciate the time and effort put into them. However having mods created exclusively for those who choose to donate (or separate ‘in-mod’ content and bonuses) is not allowed. Mod creators cannot sell modifications to Project Zomboid.

Installing and using mods

Installing mods - How to install mods for Steam or GoG version of the game

Using mods - How to enable and configure mods

Solution to the most common problems with mods - What to do if mods do not work well or break the game

Tip: Join PZ Discord for get access to #mod_support chat, where you can ask any question about using mods.

Creation of mods

Introduction

In modding for PZ, there are several main directions:

• Changing scripts - Scripts in the game describe the parameters of items, recipes and vehicles. Making a mod that changes the values ​​of items, vehicles, a recipe, or adds a new item is not a difficult. This does not require programming knowledge and any text editor is needed from the tools. Scripts are in .txt files and have a specific structure.
• Writing Lua code - The main direction in PZ modding. Most mods contain Lua code. PZ is developed mainly in Java and Lua, so using Lua code in mods is closely related to the exploration of Java and Lua game code. When creating more complex mods, you will have to dive into the decompiled Java code of the game. We will cover the basics of the Lua language, but you should be familiar with the basics of programming. A general understanding of the syntax of the Java language is also desirable, as you at one point you have to climb into the game code to figure out how this or that function works.
• Creating 3D Models - At the moment, with the help of mods, you can add new models of vehicles, weapons, ordinary items and clothes to the game. The game uses 2 model formats - .X and .FBX. For us to create mods with models, the .FBX format will be enough.
• Map Creation - Create locations, buildings and general environment for the game
• Creating animations - Creating animations for the character. Includes creating an animation file and integrating it into the game.
• Creating textures, pictures and icons - This direction complements the others. Models will need textures, items will need icons, interface will need certain images, maps will need textures for new tiles (new objects to be placed on the map).

Tip: Join PZ Discord for get access to #mod_development chat, where you can ask any question creating mods for PZ.

Working tools

• Text editors - Used to edit scripts and write code. Preferably use editors with Lua syntax highlighting - like Notepad++ or VS Code
• 3D Modeling - Used to work on 3D models. For example: Blender
• Image Editor - Used to create icons, textures for items and tiles. For example: GIMP, Photoshop

Beginner level

Mod structure - How the mod works and how to create a template for the mod

PZ folder structure and Zomboid folder - Description of files and folders that will be useful when developing mods

Starting the game in Debug mode - How to run the game in developer mode and use it

Script syntax - Scripting guide (.txt files) for items, recipes and translations

Introduction to Lua - Lua Language Guide

Logging and error handling - How to use logs to get game/mod information and handle errors

Create a 3D model for the item - Create a model with a texture for the item

Objects - PZ Objects, Variables and Functions

Events - PZ events and connection to them

Working with sounds and music - Adding and playing audio files

Working with spawn tables - Modifying item spawn tables

Mod Upload to Steam Workshop - How to checkout and upload a mod to Steam Workshop

ModData - Working with mod data and storing data

Creating the first mod - Guide about creating the mod "Hammer of Thor"

• Creating a template for mod
• Adding new items to the game
• Adding new recipes
• Adding items to item spawn tables
• Connecting to events (Lua)
• Adding sounds
• Adding translations for other languages

Advanced level

Tiles - Tile guide

Vehicle - Transport guide

Animations - Animation guide

TimedActions - Timed Actions guide

User Interface - User Interface guide

Occupations, Traits and Skills - Guide about Occupations, Traits and Skills

Testing mods in multiplayer - Guide about setting up the mod to work on the server

Creating a Firearms and Armor Mod - Guide about creating a mod "WWII Outfit"

• Creating melee and ranged weapons
• Creating clothes and armor
• Adding and customizing items

Creating a mod that adds a new vehicle - Guide about creating a mod "Sports car"

• Creating model and textures
• Adding and configuring vehicle

Creating a mod that adds a new map - Guide about creating a mod "Lake house"

• Creating a template for map
• Creating new tiles
• Creating buildings
• Adding a map and tiles to the game

Creating a mod that adds new animations - Guide about creating a mod "Macarena"

• Creating animation
• Adding animation to the game

Creating a mod that extends the functionality - Guide about creating a mod "Key duplicates"

• Creating TimedActions
• Working with user interface
• Adding profession, perk and skill

Creating a mod with a client-server architecture - Guide about creating a mod "ATM"

• Working with client-server commands
• Working with global ModData

Useful articles and links

• Files - Guide about working with files
• In-Game Mod Loading - Mod Load Order and Mod File Load Order
• Decompiling the game code - How to study the Java source code of the game