Modding

This page has been updated to an unstable beta version (42.0.2).

There may be additional features that are not in the stable version (41.78.16).

This version is part of a public beta that must be opted into.
Parts of this page may have been automatically updated to the latest unstable build (42.0.2).

This article is about an overview about modding. For PZwiki project, see PZwiki:Project Modding.

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

Terms & Conditions

By playing Project Zomboid, you agree to the Terms & Conditions.

By modding Project Zomboid, you also agree with the Modding Policy.

Key restrictions

The Indie Stone reserves the right to implement any features in the game, irrespective of whether mods exist that accomplish the same goal.
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.

Communities

Different communities exist to get help with modding, be it installing or debugging mod problems or creating mods, maps, tiles etc :

Official Discord: Check out the Workshop category to get help on installing mods, problems with mods or developing mods.
Unofficial Modding Discord: The unofficial Modding Discord provides help on coding, modeling, animating…
Unofficial Mapping Discord: The unofficial Mapping Discord provides help on mapping and tile making.

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.
Mod problems solution – what to do if mods do not work well or break the game.
Testing mods in multiplayer – guide about setting up the mod to work on the server.

Current mods

Main article: Mods

Community Modding Projects

Community Modding Projects - this mod adds 3 major mods which are created and handled by the community, with anyone being able to add to it:
- DebugTools - adds a lot of neat tools for debuging and creating mods.
- Frameworks - tools modders can use in their mods.
- Patch - community patch to recuring problems in the game.

Note: the first one is used only to create and debug mods and is useless to most players.

The debug tools are developed by and for modders and is automatically updated every Friday at midnight UTC. You can add to the modding projects yourself with pull requests to the project Github.

How to get started

Making mods might feel challenging at first because of the lack of knowledge of modding. The best tip is to start small and while you might have a mod idea which is big, it's not a good idea to get started. You have to get used to your environment, learn the various tools available and how modding works.

Go step by step but the great part is that the limitations aren't too big in the case of Project Zomboid and usually if you have an idea, the limitations might not be the game but knowing how to do it and having the time to do so. As such test some bits, don't discourage if your first mod doesn't do great or doesn't work well because you will learn from it.

If you don't know what is doable, you can either check how other mods do it by accessing their files. Asking in the various modding #Communities is also a good idea in getting some help or finding out what you could possibly achieve with modding.

Depending on the type of modding you are interested in, the #Modding Resource Hub will provide you with the necessary resources to get started as well as links to some important pages per modding fields.

Modding fields

Scripts - allow to add items in the game with simple parameters which can be edited in any text editor. No programming knowledge is needed.
Lua API - Project Zomboid is coded in both Java and Lua but utilizing a link in-between. This part involves programming codes to create or modify features by using Lua (language).
Modeling and texturing - creating models is used when creating items. Texturing goes with it to put proper textures on your items.
Pictures and icons - needed to create items, but can also be used to make various images for the game such as fliers, moodles or UI elements.
Animating - used to create new animations for characters to visually do certain actions. It involves knowledge of 3D softwares for animating but also a small bit of XML programming required to get your animation in-game.
Mapping - tools exist to create new locations, buildings and general environments for the game.
Translations – translating the game or mods to various languages.

Working tools

Various tools might be needed depending on the type of modding you do:

Text editor – used to edit scripts and write code.
- VS Code - HIGHLY SUGGESTED, a community addon for Project Zomboid typing exists for it. See Visual Studio Code.
- Notepad++
Image editor – used to create icons, textures for items and tiles.
- GIMP
- Any tool for editing images.
3D modeling and Animating – used to work on 3D models.
- Blender - the most used by the community.
Mapping and tilemaking - TileZed, WorldEd, and tilesets – TileZed can also be downloaded and compiled from the source code on GitHub, or they can be installed (currently only for Windows), as Project Zomboid Modding Tools if the game is owned on Steam.

Other Modding tools

Free Online GUID Generator - for making GUIDs for modded clothing and outfits.

Modding Resource Hub

Modding has different fields of modding, each with their own rules and tools which will be summed up the lists below.

For a few generic resources on the subject:

Folders structure to understand Project Zomboid's folder structure, such as mod structure.
Debug mode - Explanations of how to run the game in the debug (developer) mode and how to use it.
Startup parameters - Startup parameters to launch the game with.
Mod optimization to learn various tips and tricks and good habits that will improve your mods performances.
File formats - Documentation of file formats used by game.
Procedural distributions - List of procedural distributions.

Lua (API)

Main article: Lua (API)

Project Zomboid allows modders to program functionalities via a Java implementation of Lua called Kahlua which enables Lua scripts to run within Java programs. It bases itself on Lua 5.1 with a few differences and allows the use of exposed Java class and methods from Lua scripts.

To learn how to use Project Zomboid's API, you can refer to Lua (API).

Javadoc

The Javadoc is necessary to get the full list of exposed class and methods which can be used from the Lua (API).

Decompiling game code teaches how to decompile Project Zomboid's Java to more easily understand how the game works internally and what the methods and classes in the Java doc do.

Resources on the subject

Lua (language) to learn how to code with the Lua programming language.
Lua object – a full list of available Lua Objects to be used by modders.
Lua event – a full list of available Events to hook on.
Java object – a list of informations about some Java objects which can be used with the Lua API.

See Category:Lua (API) for a list of all Lua API pages.

Scripts

Main article: Scripts

Scripts are a required step in making any type of item such as weapons, clothings or food, or to define sounds and models to be usable in the game.

Types of scripts

Item scripts - Each item in the game is set by a script, which determines the parameters of the item. Depending on the type of item, different parameters will be used.
Fixing scripts - Fixing blocks are used to fix items in Project Zomboid. For example, repairing Wood Axe with different materials such as tape, glue or custom items.
Recipe scripts - Recipes are a description of the ingredients for crafting an item and a description of the item that will result from crafting.
Evolved recipe scripts - This type of recipe is used to easily create food recipes that can be filled with many ingredients.
Sound scripts - The block sets the sound parameters, which can then be used in the game.
Model scripts - The block describes the parameters of the model that will be used.
Vehicle scripts - The block describes the parameters of the vehicle.
Multistage build scripts - The block describes an option to improve/create a multistage building.

Modeling and texturing

External resources

How To Create an Animation

Mapping and tiles

Main article: Mapping

Mapping pages

Tiledefs used by mods - List of tiledef IDs which are already used.
Adding new tiles - Guide to adding new tiles.
Tile properties - Explanation of tile properties.
Room definitions and item spawns - Explanation of room definitions, used mainly for loot distribution.
Vehicle zones - Explanation of vehicle zones.

External resources

Tutorials

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

Others

Notes

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 but the best solution is to unsubscribe from the mod, wait for the update then redownload it again. 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.

External resources

Tutorial	Author	Last updated
Project Zomboid Modding Guide (WIP)	Fenris Wolf	January 22, 2023
RoboMat's Tutorials	RoboMat	July 24, 2013
Mod Resources (Official Discord - Thread The Under Mod Development Channel)		July 21, 2024

Older resources

General additional modding resources

Clothing modding resources

Old and more specific additional modding resources

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.